JSP Web services
You can use Web services
in your JSP by generating custom tags for them. The JSP Web Service
Proxy wizard on the Web page of the New dialog box creates a custom
tag library with the information necessary for calling a Web service in
a JSP.
For more information on custom tags and custom tag libraries,
see “Custom tags”.
Using the JSP Web Service Proxy wizard
The wizard collects information such as the location of a
Web Services Description Language (WSDL) file, the service, and
port. You can specify overrides to the WSDL file for a custom bean
name, Java class name, Java package name, TLD name, JAR file name,
output variables, and the selection of operations within a service.
The wizard creates a TLD file, the Java source to process the custom
tag, and the compiled Java class files of the source.
The wizard supports WSDL files with Remote Procedure Call
(RPC) encoding, and can display the services, operations, ports,
and method signatures related to RPC-encoded Web services. Any document-literal,
document-encoded, or RPC-literal elements in the WSDL file are ignored
by the wizard.
The wizard can process a WSDL file without requiring additional
class files (and property files registering user-defined datatypes)
if the Web service referenced by the WSDL includes only the following
datatypes:
- Simple XSD datatypes (string, short, long, int, float, double, boolean, void, byte)
- Arrays, including multi-dimensional arrays, of supported
datatypes - Jaguar and Java holder datatypes
PowerBuilder client Web services wizard The JSP Web Service Proxy wizard is similar to the Web Service
Proxy wizard on the Project page of the New dialog box, but the
latter creates a PowerBuilder client for a Web service and can only
be used in PowerScript targets.
For more information about Web services and the Web Service
Proxy project wizard, see the chapter on Web services in Application
Techniques
.
Files added by the JSP Web Service Proxy wizard
The JSP Web Service Proxy wizard adds a client class JAR,
logging, and property files to JSP target subdirectories, in addition
to TLD and WSDL files, and a JAR file containing TLD classes. These
client, logging, and property files are copied from the Class and
Lib subdirectories of the SybaseSharedPowerBuilderWEB-INF
directory. When you deploy the JSP target, the copied files are
deployed along with the other target files.
| File added by wizard | Description |
|---|---|
| tldsService_Name.tld | A default file name is provided by the Web service WSDL, but the JSP Web Services Proxy wizard lets you rename the TLD file that it adds to the target. |
| liblog4j-1.2.3.jar | Contains the Log4j logging classes from the Apache Jakarta project. |
| libService_Name.jar | A default file name is provided by the Web service WSDL, but the JSP Web Services Proxy wizard lets you rename the JAR file that it adds to the target. |
| libswsclient.jar | Contains client classes for accessing a Web service. |
| classesesdweblogger.props | Determines the name and location for the file that logs JSP target activity, contains instructions for turning on logging, and sets the level of logging that occurs. By default, the log file name is esdweb.log. You must supply a full path to make sure the log file is created where you want it. |
| classesWebService.wsdl | WSDL file you select in the wizard. |
| classessyuproxy.props | Contains property-value pairs for information needed by the Web Services Proxy. Use this file to specify a default directory for locating WSDL files and the location of the user.encoding.props file. It also specifes the key store that holds certificates needed for https connections. |
| classesuser.encoding.props | Default file that serves as a placeholder. You must modify or replace this file if the Web service you want to access requires user defined datatypes. For more information, see “Web services with user datatypes”. |
Other files required on the JSP server
At runtime, the JSP server where you deploy your target must
have additional files in its class path for a Web service to work.
If your server does not have these files in its class path, you
can copy them to a directory in the server class path from the SybaseSharedPowerBuilderWEB-INFlib
directory. These files are not deployed with your JSP target.
| Required files | Description |
|---|---|
| xercesImpl-2.1.0.jar | The version of the xerces.jar from Apache that has been tested with PowerBuilder. |
| xml-apis.jar | Used for XML parsing. |
| jcert.jar, jnet.jar, and jsse.jar | Used for HTTPS connections over SSL. These files are not required for Web services on pages using HTTP connections. |
Adding a custom tag for Web services
Once you have
generated your custom tag, it appears in the System Tree. When you
drag it to a JSP, the tag library is automatically associated with
the page. You must specify the input and output arguments for the
custom tags for the Web services in the JSP. Output arguments are
stored in the pageContext of the JSP container.
Deployment of the custom tag for Web services is the same
as deployment of any custom tag in PowerBuilder. See “Editing a JSP deployment
configuration” for details.
Custom tags for Web services throw a JspTagException for nonrecoverable errors.
The JspTagException contains information about the root cause of
the exception and the point the error occurred in processing the
custom tag. This exception can be caught in a Try-Catch block or
mapped to a specific error page in the Deployment Configuration
Properties dialog box for the JSP target. An error page can also
be specified in a page directive. See “Error handling” and “Error Mapping” for details.
Example using a currency exchange Web service
This example, using the currency exchange service available
on the XMethods Web site
, demonstrates how custom tags for
Web services on a JSP are defined to a JSP container. You proceed
with these steps after generating a TLD and JAR file for the service
using the JSP Web Service Proxy wizard. The remainder of this example
assumes that you accept all the wizard defaults after selecting
the CurrencyExchangeService.wsdl file.
First you declare the custom tag library to the JSP. This
makes all of the tags in the library available to the JSP. The exchange prefix
allows for easy reference to the tag library. You can drag the library
from the Components tab of the System Tree to the JSP in the HTML
editor to add this code.
|
1 |
<%@ taglib uri="WEB-INF/tlds/CurrencyExchangeService.tld"<br /> prefix="exchange" %> |
Once the tag library is available to the page, you declare
the input arguments for the custom tags in a server script.
|
1 |
<%<br /> String firstCountry = "usa";<br /> String secondCountry = "japan";<br /> %> |
Next, you invoke the Web service through the custom tag, passing
the input parameters in a server-side expression.
|
1 |
<exchange:getRate country1="<%= firstCountry %>"<br /> country2="<%= secondCountry %>" /> |
Then you get the value of the returnValue variable
from the custom tag and display it. This value is set when the tag
is executed.
|
1 |
<P>The exchange rate between "<%= firstCountry %>" and "<%= secondCountry %>" is: <br /> <%= CurrencyExchangeService_getRate_returnValue %></P> |
Web services with user datatypes
If
a Web service requires a complex datatype for an input or output
parameter or return value, the corresponding WSDL Part element may
contain a Type attribute, such as prefix:localpart,
where prefix is a reference to the namespace that
governs the type and localpart is the name
of the XML element that describes the type. The prefix may refer
to the current WSDL document or some other XML document. The namespace
referenced by the prefix must contain a definition of the datatype
named by the localpart.
For example, the AirportWeather.wsdl on
the CapeClear Web site contains a Part element with the Type attribute xsd1:WeatherSummary.
The Schema element nested in the Types element of the same WSDL
file also contains a WeatherSummary element.
The WeatherSummary element is composed of seven xsd:string types.
(The xsd:string types are defined in the XML schema
.) In this case, you need to create and compile
a Java class for the JSP Web service client that defines the WeatherSummary datatype.
Once the Java class is created, place it in the SharedPowerBuilderWEB-INFclasses directory
in the Sybase path. In your JSP target, import or copy the compiled
class to the SourceWeb-INFclasses directory
of your target.
Registering user defined types
Before deploying a JSP Web service client, you must update
the user.encoding.props file to include the
user defined type. In this case, to register the WeatherSummary
class, you would add the following entry using no blank spaces:
|
1 |
soap.user.encodings=WeatherSummary,com.sybase.esdweb.<br /> soap.encoding.BeanSerializer,com.sybase.esdweb.soap.<br /> encoding.BeanSerializer,http://www.capeclear.com/<br /> AirportWeather.xsd,http://schemas.xmlsoap.org/soap/<br /> encoding/ |
This entry corresponds to the follwing comma-separated items:
the fully qualified class name, the fully qualified class name of
the serializer, the fully qualified class name of the deserializer,
the URI of the encoding style being used for the type, and the URI
of the schema defining the serialization rules for the type.
If another entry for a user defined type is already within
the file, separate the entries with a semicolon. By registering
the user defined type, the client-side SOAP processing is able to
extract data from the user defined type supplied by the JSP, use
the data to create a SOAP request, retrieve data from the SOAP response,
and fill the user defined type returned to the JSP.
If you save the user.encoding.props file
to the SybaseSharedPowerBuilderWEB[Unmapped Entity: shy ]
[Unmapped Entity: shy ]
-INFclasses directory,
it will be copied to the target sourceWeb-Infclasses directory
and contained in the target WAR file when you deploy your target.
The user.encoding.props file must be in the runtime
classpath. Alternatively, you can set the location of the user.encoding.props file
in the syuproxy.props file.
Example Java code for a user datatype
For example, the Airport Weather service on the Cape Science Web site
contains a complex datatype
defined in the WSDL as xsd1:WeatherSummary.
When the Web service returns an object of this datatype to a client,
the client must be able to process the object. Therefore you must
create a Java class definition for this datatype and have this available
to the JSP application.
The WeatherSummary datatype is a combination of many string
values into a single data structure with get and set methods
for each of the strings. It contains a zero-argument constructor.
The following is Java code for creating the WeatherSummary class:
|
1 |
public class WeatherSummary <br /> {<br /> private String location="";<br /> private String wind="";<br /> private String sky="";<br /> private String temp="";<br /> private String humidity="";<br /> private String pressure="";<br /> private String visibility="";<br /> <br /> public void setLocation( String location )<br /> { this.location = location; } ... //set methods for other data members<br /> <br /> public String getLocation( ) <br /> { return this.location; } ... //get methods for other data members |
|
1 |
} |