| In the previous article,
we discussed using very simple Web services - Web services that
would only return primitive data structures such as a single string,
number, and so forth.
If we had to build all our applications only using simple return
structures such as this, the applications would not be that useful.
Let's now discuss returning far more interesting information from
our Web service.
A limitation with LotusScript (and the Basic language in general)
is that we can only return one "thing" at a time. That thing might
be:
- A simple (or primitive) data item such as a string, number,
or so forth
- A variant containing just about anything
- An instance of a class
A limitation of Web services is that the Variant data type is not
supported - hardly surprising as it would be an almost impossible
exercise to come up with data structures that deal with all possible
variant contents.
This leaves us with our last option, which is returning an instance
of a class.
As you recall from the last article, a class is a LotusScript construct
that allows you to bind data and functions together. In terms of
classes that are exposed to Web services (within the "Web service"
design type in Notes/Domino 7), all public functions are exposed
to Web services.
For example, our simple class:
As this class is exposed to Web services, we have a very simple
Web service that exposes a single function that, in turn, returns
a single string. This isn't very useful at this point in time.
The next function we shall implement is to list all users in our
database. This will return zero or more user names in a string array.
But as previously discussed, we cannot return collections (such
as arrays or lists) directly from a LotusScript function, and we
cannot put them into a Variant data type.
The solution is to construct another class:
As you can see, this class contains just one public member - the
String array "S." (In terms of best practices, this is a pretty
horrible naming strategy I know, but it does keep the code examples
readable.)
Now, within our new function in our "Contact" class, we can have
the function:
This will then be returned by the Web service as class returnStringArray,
which in turn just contains an array of strings. Most Web service
consumers (and certainly the BlackBerry MDS toolkit) will immediately
resolve this to a string array
All we now have to do is populate this string array:
And that's it. We've populated a string array with a value from
each document in our view, and returned that function. That wasn't
as hard as it sounded!
If we take this one step further, instead of passing back just
a string array, we can pass back a more detailed structure. For
instance, consider the "Contact" class
We could then return this as a Web service return result by:
Now that our Web service has been updated, we can refresh our BlackBerry
application. This will then recognize these new methods, and add
in relevant screens and data definitions.
Now that we have our new Web service functions in place, let's
go off and refresh our BlackBerry MDS application to incorporate
these functions.
- Open the BlackBerry MDS Studio and expand our project.
Expand the "Data Sources" entry, and select the entry for
the Web service. Right click the Web service and select
"Data Source Update."
|
 |
- You will be prompted to confirm the
Web site address
|
 |
- Our new operations are updated. On
this dialog box, select the entry in the "Action for MDS
Components" column and change it from "Ignore" to "Bind
with QuickStart"
Click the "Finish" button to complete this operation.
|
 |
- We should now find a number of new
screens in our application that we can now work with. As
before, the screens have been built using a standard graphical
look and feel and need to be updated. Use the actions in
the previous article to refresh the following screens:
- scrLISTUsersResponse
- scrGETUSERDETAILSResponse
|
|
- Let's open screen scrLISTUSERResponse.
|
 |
- As you can see, a radio button has
been added automatically to this screen, and has the initial
value "@gLISTUSERResponseArray[]." Basically this means
that the results of the Web service "List Users" function
will then populate this radio button.
|
|
I use the phrase "Chaining Requests" in order to indicate that
the user should use the results of one operation - perhaps searching
for a user in order to get a username - in order to execute a second
operation, such as requesting more information on that user.
The BlackBerry MDS toolkit makes this very simple for us by holding
the parameters and the results for all Web service operations in
global variables within the application. This means that we can
easily direct the output of one operation to the input of the next.
We'd like to link the user selection from the button on the LISTUsersResponse
screen to the GetUserDetails operation. How can we do that?
It's simply a case of mapping the output of the radio button to
a global variable, and then changing the button to run the "GetUsersDetails"
operation.
- Open the scrLISTUsersResponse screen.
|
|
- Click the radio button, and then click
the button on the mapping field in the properties box.
We can now select a global variable to put the output into.
As you can see, global variables have already been defined
as part of the process of importing the Web service definition,
and each operation input and output is defined using a naming
convention.
In this case, we shall select gGETUSERDETAILSRequest - "g"
for Global, the name of the operation, and "Request" for
an input.
|
 |
- Lastly, let's change the "Done" button
to "Select," and change the button action from opening a
screen to running a script. Select the "Done" button and
in the properties window:
- Change the caption.
- Click the On Click event, and change
the event from a screen transition to run a script.
In the Script drop-down box, choose the script GETUSERDETAILSRequest
|
 |
So far, we've restricted ourselves to using the standard fonts
and colors in our applications, which doesn't give our application
the required feel.
One good thing about the MDS Studio is that it allows you to define
a style for a piece of text, and apply that style throughout the
application. This means that if you have to change your font, size,
color, etc., you won't have to go hunting through all the screens
to update them.
In order to create a style:
- Expand your application browser on
the left hand pane, and right click "Styles."
|
 |
- Assign this style a name. In this case,
let's define how our label text will appear.
Enter "Labels" in the name field, and click on "Finish."
|
 |
- In this case, we're going to change
the foreground color of the text from black to dark-grey.
|
 |
To assign a style, we need to select a screen element.
- Open screen scrFINDUSERRequest and
click the "SEARCHSTRING" label element.
|
 |
- On the right-hand property box, click
the Style property and select "Labels" from the drop-down
list.
|
 |
- You can now choose one of the styles
you created earlier.
|
 |
And that's all there is to it!
You are not restricted to a single Notes database in terms of the
reach of the code you put behind your Web service.
Remember that we can write a Web service server in Notes and have
it execute any piece of LotusScript, which can include opening other
databases. This means that you may wish to write one Web service
that consolidates information for one set of Web service requests
from many databases, thus simplifying the Web service output.
Or you may wish to write your Web service in a separate database,
in order to take advantage of a different ACL, or because you may
not be able to update the application itself.
|