Date: 07/02/02
OC4J Web Services features allow you to expose your business logic implemented as pure Java class(es), PL/SQL store procedures or EJB session beans as web services. OC4J supports both stateless and stateful web services. For stateless web services, OC4J will create multiple instances of the web service implementation in a pool, and any one of which may be used for serving a web service request. For stateful web services, a servlet HttpSession is used to maintain the object state between requests from the same client. To expose your business logic as a OC4J web service, you publish your business logic implementation as a web service servlet, assemble it into a web service archive and deploy it to OC4J. OC4J then generates the WSDL and the necessary client side jar files to build your web services client.
There are four types of web services implementation supported by OC4J:
OC4J creates a "web service" servlet for each web service implementation (which could be either a pure Java class, a PL/SQL store procedure or a EJB session bean), and this servlet is served as a translator between the web service client and the web service implementation. It receives the SOAP request from the web service client, and translate the request parameters before dispatching the call to the actual web service implementation. On the other hand, the servlet translates the execution result from the web service implementation, and sends back the SOAP response to the web service client. The "web services servlet" implementations are part of OC4J, and you don't need to worry about how the transaction and dispatching work is done, however, you do need to provide the mapping between your web service implementation with the servlet to OC4J. Web service implementation needs to be packaged as a Web Service Archive file before deploying it to OC4J. A web service archive file is a standard J2EE EAR file. It contains the web service implementation, and some web services specific configuration in the web module's WEB-INF/web.xml.
Depending on the types of web services, the required OC4J web services configurations are different:
For stateless pure Java web service, you add the implementation class(es),
and any required support libraries to the WAR file, either under WEB-INF/classes
or WEB-INF/lib of your web service archive. You then publish a web service servlet
for the web service as follows in WEB-INF/web.xml:
<servlet>
<servlet-name>stateless java web service</servlet-name>
<servlet-class>oracle.j2ee.ws.StatelessJavaRpcWebService</servlet-class>
<init-param>
<param-name>class-name</param-name>
<param-value>myJavaClass.class</param-value>
</init-param>
<init-param>
<param-name>interface-name</param-name>
<param-value>myJavaInterface.class</param-value>
</init-param>
</servlet>
...
<servlet-mapping>
<servlet-name>stateless java web service</servlet-name>
<url-pattern>/statelessTest</url-pattern>
</servlet-mapping>
A stateful pure Java web service configuration is identical to the stateless
pure Java case above, except that the value of the <servlet-class>
is oracle.j2ee.ws.JavaRpcWebService. In the stateful Java web service
case, there is an additional init parameter that controls the timeout of the
session, <session-timeout>. The parameter is optional, and its value is
the number of seconds the session remain inactive before timing out the session.
A stateless PL/SQL web service is identical to the stateless pure Java web service above, except it requires one additional <init-param> inside <servlet> declaration in WEB-INF/web.xml:
<init-param>
<param-name>datasoruce-JNDI-name</param-name>
<param-value>OracleCoreDS</param-value>
</init-param>
This parameter contains the JNDI name of the backend database. The actual definition
of the database source is described in %J2EE_HOME%/config/data-sources.xml
config file. The database should contain the PL/SQL store procedures that implement
the web service. Procedures or functions declared at the top-level are not supported,
and you need to explicitly place them inside a package before exposing them as
web services. A PL/SQL store procedure needs be translated into Java using Oracle
JPublisher before exposing as web services.
For stateless session EJB web service, add the EJB jar file to the top level
of the web service archive as you do for a standard EAR packaging. Then you
publish a web service servlet for the web service as follows in WEB-INF/web.xml:
<servlet>
<servlet-name>stateless session bean web service example</servlet-name>
<servlet-class>oracle.j2ee.ws.SessionBeanWebService</servlet-class>
<init-param>
<param-name>jndi-name</param-name>
<param-value>ejb/myEjb</param-value>
</init-param>
</servlet>
...
<servlet-mapping>
<servlet-name>stateful java web service example</servlet-name>
<url-pattern>/statelessEjb</url-pattern>
</servlet-mapping>
...
<ejb-ref>
<ejb-ref-name>ejb/myEjb</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-name>
<home>myEjbHome</home>
<remote>myEjbRemote</remote>
<ejb-link>myEjbName</ejb-link>
</ejb-ref>
Once you have specified the web services specific configuration, you can package your web service implementation into a web service archive. A web service archive is a standard J2EE EAR file. You may use the OC4J admin utility to deploy the web service archive.
As an alternative to manually specifying the above configurations, you may use a command line tool - Web Services Assembler to produce web service archive. The input of the assembler is a XML config file which describes the type of web service to be exposed, the location of the web services implementation, and other mandatory configuration parameters required by OC4J to assemble the web services. The output of the assembler is a web service archive. A web service archive is a standard J2EE EAR file, and you then use the OC4J J2EE deployment tool to deploy the archive.
The following Web Services Assembler configuration file shows how to define three types of web services (stateless Java, statefull Java, stateless session EJB) to be wrapped in an Enterprise ARchive:
<?xml version="1.0"?>
<!DOCTYPE application-server PUBLIC "Orion Application Server Config" "http://xmlns.oracle.com/ias/dtds/webservices-assembler.dtd">
<web-service>
<display-name>Web Services Demo</display-name>
<description>This is a demo.</description>
<destination-path>/tmp/work/ws_example.ear</destination-path>
<temporary-directory>/tmp</temporary-directory>
<context>/webservices</context>
<stateless-java-service>
<interface-name>StatelessExample</interface-name>
<class-name>StatelessExampleImpl</class-name>
<uri>/statelessTest</uri>
<java-resource>/tmp/work/stateless/</java-resource>
</stateless-java-service>
<stateful-java-service>
<interface-name>StatefulExample</interface-name>
<class-name>StatefulExampleImpl</class-name>
<uri>/statefullTest</uri>
<java-resource>/tmp/work/statefull/</java-resource>
</stateful-java-service>
<stateless-session-ejb-service>
<path>/tmp/work/ejb/MyCart.jar</path>
<uri>/statelessEjbTest</uri>
<ejb-name>Cart</ejb-name>
<ejb-resource-path>/tmp/work/ejb/</ejb-resource-path>
/>
</web-service>
After you have deployed the web service archive to OC4J, the WSDL of the web
service and the client side stubs can be generated on demand. To access the
WSDL of the web service, point your browser to http://host:port/<context-root>/<url-pattern>?wsdl.
To access the client side proxy stubs, point your browser to http://host:port/<context-root>/<url-pattern>?proxy_jar
(proxy_source for source code). The <context-root> value is the <context-root>
element value you specified in the META-INF/application.xml of your web service
archive; the <url-pattern> value is the <url-pattern> element value
you specified in the WEB-INF/web.xml of your web module in the web service archive.
The proxy jar file contains a Java class to serve as a proxy of the web service
implementation reside in the server, it must be included in the CLASSPATH of
your client application. Building the web services static client is simple because
all the work to construct the soap request, marshal and unmarshal the parameters,
..., etc. are handled by the OC4J web services proxy jar file. For each method
exposed on the web service, there is a correspondent method in this proxy class,
all you need to do is creating a client proxy and invoke the methods as follows:
MyWebServiceProxy proxy = new MyWebServiceProxy();
proxy.myMethod(...);
ant
ant deploy-usingadmin.jar
ant cli-jar
ant
ant deploy-usingadmin.jar
ant cli-jar
This example calles a simple stateless EJB via a web service. The example is
in the directory <example_home>/ejb. The directory
contains the following files and directories:
ant
ant deploy-usingadmin.jar
ant cli-jar