Oracle9i Application Server Web Services Developer's Guide Release 2 (9.0.3) Part Number B10004-01 |
|
The Oracle9iAS Web Services assembly tool, WebServicesAssembler
, assists in assembling Oracle9iAS Web Services. The Web Services assembly tool takes a configuration file which describes a Web Service, including the location of the Java classes, PL/SQL stored procedures or functions, or J2EE EAR, WAR, or JAR files and produces a J2EE EAR file that can be deployed under Oracle9iAS Web Services.
This chapter contains the following topics:
Run the Web Services assembly tool as follows:
java -jar WebServicesAssembler.jar [-debug] -config [file] or java -jar WebServicesAssembler.jar [-debug]
Where file is a Web Services assembly tool configuration file. Without the -config
option, a file named config.xml
must be present in the same directory where WebServicesAssembler.jar
is invoked.
With the -debug
option, WebServicesAssembler
displays verbose debugging comments.
The sample configuration file shown in Example 9-1 defines two services to be wrapped in an Enterprise ARchive file (EAR). The sample includes configuration information for services defined with <stateless-java-service>
and <stateful-java-service>
tags.
<web-service> <display-name>Web Services Example</display-name> <description>Java Web Service Example</description> <!-- Specifies the resulting web service archive will be stored in ./ws_example.ear --> <destination-path>./ws_example.ear</destination-path> <!-- Specifies the temporary directory that web service assembly tool can create temporary files. --> <temporary-directory>./tmp</temporary-directory> <!-- Specifies the web service will be accessed in the servlet context named "/webservices". --> <context>/webservices</context> <!-- Specifies the web service will be stateless --> <stateless-java-service> <interface-name>oracle.j2ee.ws_example.StatelessExample</interface-name> <class-name>oracle.j2ee.ws_example.StatelessExampleImpl</class-name> <!-- Specifies the web service will be accessed in the uri named "statelessTest" within the servlet context. --> <uri>/statelessTest</uri> <!-- Specifies the location of Java class files are under ./src --> <java-resource>./src</java-resource> </stateless-java-service> <stateful-java-service> <interface-name>oracle.j2ee.ws_example.StatefulExample</interface-name> <class-name>oracle.j2ee.ws_example.StatefulExampleImpl</class-name> <!-- Specifies the web service will be accessed in the uri named "statefullTest" within the servlet context. --> <uri>/statefulTest</uri> <!-- Specifies the location of Java class files are under ./src --> <java-resource>./src</java-resource> </stateful-java-service> </web-service>
After running the Web Services Assembly tool with the sample input file shown in Example 9-1, the generated output is an EAR file (/tmp/ws_example.ear
) The generated J2EE .ear file, ws_example.ear
, has the structure shown in Example 9-2.
ws_example.ear |---META-INF | `---application.xml `---ws_example_web.war |---index.html `---WEB-INF |------web.xml `------classes `------oracle `-----j2ee `---ws_example |---StatefulExample.java |---StatefulExample.class |---StatefulExampleImpl.java `---StatefulExampleImpl.class |---StatelessExample.java |---StatelessExample.class |---StatelessExampleImpl.java `---StatelessExampleImpl.class
This section describes using the <wsdl-gen>
and <proxy-gen>
tags in a WebServicesAssembler
configuration file. These tags controls the options for generating WSDL files and client-side proxies for Web Services. A client-side developer can obtain and use the WSDL file or the client-side proxies to build an application that uses a Web Service. A server-side developer that is assembling Web Services can use these file for testing Web Services.
This section covers the following topics:
Using Oracle9iAS Web Services, a Web Service developer has several choices for deciding how the WSDL file that is associated with a Web Service is generated:
<wsdl-gen>
tag, you can specify that WebServicesAssembler
create the WSDL file. At assembly time when the Web Service is prepared, the WebServicesAssembler
generates and packages the WSDL file with the Web Service.
Example 9-3 shows a configuration file that includes the <wsdl-gen>
tag.
<wsdl-gen>
tag in the configuration file.
<wsdl-gen>
tag during assembly of the J2EE .ear file to specify the path to the WSDL file. At assembly time when the Web Service is prepared, the WebServicesAssembler
packages the WSDL file with the Web Service.
Table 9-1 describes the <wsdl-gen>
WebServicesAssembler
configuration file sub-tags.
<web-service> <display-name>Stateless Java Document Web Service</display-name> <description>Stateless Java Document Web Service Example</description> <destination-path>./statelessdocws.ear</destination-path> <temporary-directory>./temp</temporary-directory> <context>/statelessdocws</context> <option name="source-path">converter.xsl</option> <stateless-java-service> <interface-name>StatelessDoc</interface-name> <class-name>StatelessDocImpl</class-name> <uri>/docservice</uri> <java-resource>./classes</java-resource> <message-style>doc</message-style> </stateless-java-service> <!-- generate the wsdl --> <wsdl-gen> <wsdl-dir>wsdl</wsdl-dir> <!-- over-write a pregenerated wsdl , turn it 'false' to use the pregenerated wsdl--> <option name="force">true</option> <option name="httpServerURL">http://localhost:8888</option> </wsdl-gen> </web-service>
When you do not want to use either the WebServicesAssembler
tool generated WSDL or the Oracle9iAS Web Services runtime generated WSDL file, and you want to supply your own version of the Web Service WSDL file, perform the following steps:
.wsdl
extension placed after the service name. For example, service1.wsdl
for a service named service1
.
<wsdl-gen>
tag, including <option name="force">
set to false
and <option name="packageIt">
set to true
.
<wsdl-dir>
tag.
WebServicesAssembler
with the specified configuration file.
When the <proxy-gen>
tag is included in a configuration file with the <wsdl-gen>
, the generated WSDL is used to generate the proxy that is placed in the specified directory (this occurs when WebServicesAssembler
runs during the Web Service assembly process).
Table 8-2 lists the <proxy-gen>
sub-tags.
Example 9-4 shows a sample configuration file that includes both the <wsdl-gen>
and the <proxy-gen>
tags.
<web-service> <display-name>Test</display-name> <description>Test program</description> <destination-path>test.ear</destination-path> <temporary-directory>temp/</temporary-directory><context>/HotelService</context> <option name="source-path">Workspace1/common/classes</option> <stateless-java-service> <interface-name>com.mypackage1.Itest</interface-name> <uri>/main</uri> <class-name>com.mypackage1.test</class-name> </stateless-java-service> <wsdl-gen> <wsdl-dir>wsdl</wsdl-dir> <option name="force">true</option> <option name="httpServerURL">http://localhost:8888</option> <option name="packageIt">false</option> </wsdl-gen> <proxy-gen> <proxy-dir>proxy</proxy-dir> <option name="include-source">true</option> </proxy-gen> </web-service>
The input file for WebServicesAssembler
is an XML file conforming to the Web Services Assembly Tool configuration file DTD.
Example 9-5 shows the Web Services Assembly Tool Configuration file DTD.
<?xml version="1.0" encoding="UCS-2"?> <!-- Specify the properties of the web services to be assembled. --> <!ELEMENT web-service ((display-name)?,(description)?,destination-path,temporary-directory,context,(datasource-JNDI-name)?,(statefu l-java-service)*,(stateless-java-service)*,(stateless-stored-procedure-java-service)*,(stateless-session-ejb- service)*,(jms-doc-service)*,(option)*,(wsdl-gen)?,(proxy-gen)?)> <!ELEMENT display-name (#PCDATA)*> <!ELEMENT description (#PCDATA)*> <!-- Specify the full path of the resulting EAR file. For example, "/home/demo/webservices.ear" --> <!ELEMENT destination-path (#PCDATA)*> <!-- Specify a directory where the assembly tool can create temporary directories and files. --> <!ELEMENT temporary-directory (#PCDATA)*> <!-- Specify the context root of the web services. For example, "/webservices". --> <!ELEMENT context (#PCDATA)*> <!-- for specifying database resource refs --> <!ELEMENT datasource-JNDI-name (#PCDATA)*> <!-- Specify the properties of a stateful Java service --> <!ELEMENT stateful-java-service ((interface-name)?,class-name,uri,(java-resource)*,(ejb-resource)*,(scope)*,(session-timeout)*,(message-style )?)> <!-- Specify the properties of a stateless Java service --> <!ELEMENT stateless-java-service ((interface-name)?,class-name,uri,(java-resource)*,(ejb-resource)*,(message-style)?)> <!-- Specify the properties of a stateless stored procedure Java service --> <!ELEMENT stateless-stored-procedure-java-service ((interface-name)?,(class-name)?,uri,database-JNDI-name,(java-resource)?,(jar-generation)?)> <!-- Specify the properties of a stateless session ejb service --> <!ELEMENT stateless-session-ejb-service (path,uri,ejb-name,(ejb-resource)*)> <!-- Specify the java interface which defines the public methods to be exposed in the web service. For example, "com.foo.myproject.helloWorld". --> <!ELEMENT interface-name (#PCDATA)*> <!-- Specify the java class to be exposed as a web service. If interface-name is not specified, all the public methods in this class will be exposed. For example, "com.foo.myproject.helloWorldImpl". --> <!ELEMENT class-name (#PCDATA)*> <!-- Specify the uri of this service. This uri is used in the URL to access the WSDL and client jar, and invoke the web service. For example, "/myService". --> <!ELEMENT uri (#PCDATA)*> <!-- Specify the java resources used in this service. The value can be a directory or a file that implements the web services. If it is a directory, all the files and subdirectories under the directory are copied and packaged in the Enterprise ARchive. If the java resource should belong to a java package, you should either package it as a jar file and specify it as a java resource, or create the necessary directory and specify the directory which contains this directory structure as java resource. For example, you want to include "com.mycompany.mypackage.foo" class as a java resource of the web services, you can either package this class file in foo.jar and specify <java-resource>c:/mydir/foo.jar</java-resource>, or place the class under d:/mydir/com/mycompany/mypackage/foo.class and specify the java resource as <java-resource>c:/mydir/</java-resource>. --> <!ELEMENT java-resource (#PCDATA)*> <!-- Specify the ejb resources used in this service. ejb-resource should be a jar file that implements a enterprise java bean. --> <!ELEMENT ejb-resource (#PCDATA)*> <!-- Specify the database JNDI name for stateless PL/SQL web service. --> <!ELEMENT database-jndi-name (#PCDATA)*> <!-- Specifies the path of the EJB jar file to exposed as web services. --> <!ELEMENT path (#PCDATA)*> <!-- Specify the ejb-name of the session bean to be exposed as web services. ejb-name should match the <ejb-name> value in the META-INF/ejb-jar.xml of the bean. --> <!ELEMENT ejb-name (#PCDATA)*> <!-- Specify scope of Statefull Java service --> <!ELEMENT scope (#PCDATA)*> <!-- Specify session timeout of Statefull Java service --> <!ELEMENT session-timeout (#PCDATA)*> <!-- Specify the directory location of the generated wsdl--> <!ELEMENT wsdl-dir (#PCDATA)*> <!-- Specify that wsdl generation is to happen 'force' 'httpServerURL' 'packageIt'--> <!ELEMENT wsdl-gen (wsdl-dir,(option)*)> <!-- Specifyg the directory location of the generated proxy--> <!ELEMENT proxy-dir (#PCDATA)*> <!ELEMENT option (#PCDATA)*> <!ATTLIST option name CDATA #REQUIRED> <!-- Specifying that proxy generation is asked for , it can have optional tags as 'include-source' 'wsdl-location' --> <!ELEMENT proxy-gen (proxy-dir,(option)*)> <!ELEMENT jar-generation (db-package-name,db-schema,db-url,prefix,(method-name)*)> <!ELEMENT database-JNDI-name (#PCDATA)*> <!ELEMENT db-package-name (#PCDATA)*> <!ELEMENT db-url (#PCDATA)*> <!ELEMENT db-schema (#PCDATA)*> <!ELEMENT prefix (#PCDATA)*> <!ELEMENT method-name (#PCDATA)*> <!-- specify the message style ,if this tag is not present it is considered to have 'rpc' ..it can have values of 'rpc' or 'doc' or 'document' --> <!ELEMENT message-style (#PCDATA)*> <!ELEMENT connection-factory-resource-ref (#PCDATA)*> <!ELEMENT topic-resource-ref (#PCDATA)*> <!ELEMENT queue-resource-ref (#PCDATA)*> <!--Resource ref of the return destination factory--> <!ELEMENT reply-to-connection-factory-resource-ref (#PCDATA)*> <!--Resource ref of the return destination Topic. --> <!ELEMENT reply-to-topic-resource-ref (#PCDATA)*> <!--Resource ref of the return destination Queue. --> <!ELEMENT reply-to-queue-resource-ref (#PCDATA)*> <!--jms-priority ,jms-message-type,jms-delvery-mode ,jms-expiration The JMS properties are only set for enqueuing operations, i..e, for send operations only. --> <!ELEMENT jms-priority (#PCDATA)*> <!ELEMENT jms-message-type (#PCDATA)*> <!ELEMENT jms-delivery-mode (#PCDATA)*> <!ELEMENT jms-expiration (#PCDATA)*> <!-- operation property is optional. Possible values for this parameter are: send, receive, and both. If not provided, the value defaults to both. --> <!ELEMENT operation (#PCDATA)*> <!ELEMENT jms-doc-service (uri,connection-factory-resource-ref,(topic-resource-ref)?,(queue-resource-ref)?,(reply-to-connection-factory -resource-ref)?,(reply-to-topic-resource-ref)?,(reply-to-queue-resource-ref)?,(jms-priority)?,(jms-message-ty pe)?,(jms-delivery-mode)?,(jms-expiration)?,(operation)?)>
The WebServicesAssembler
tool has the following limitations:
|
![]() Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|