This example shows how to develop a Document Literal style webservice for Oracle 10iAS using the Top-Down paradigm. Document Literal webservices are services that process xml documents. The Top-Down paradigm implies that you are starting with a WSDL and will write the implementation classes after the WSDL has been processed and the necessary service classes and interfaces are generated. Once the generation process is complete your implementation class can be compiled and included into the webservice archive (EAR file) to be deployed to OC4J. For your convenience this example has an implementation class and corresponding source code.
Quick StartEnsure that you have installed the required software and set up your environment. You must have OC4J running. If it is not running on localhost, port 8888, you'll have to modify the ANT script (build.xml) to use the correct host and port to your server.
Once you have the server configured and running, just type ant from the top_down/doclit directory. The service artifacts and implementation class will be compiled and placed into a WAR which is then placed into an EAR. The EAR will be deployed to OC4J. Next the stubs and client will be compiled. Finally the service will be invoked by the client and you should see the output both in the server's message output and on the stdout of the client.
Step By Step
In this step you will generate the service artifacts which include interfaces
and Tie classes.
Examine the service-config.xml file. Notice that
the implementation-class-name element is filled in with the implentation
class provided by the demo. This class is not compiled yet so WSA will generate
the artifacts and use the class name as a place holder. Once the artifacts
are generated, the implementation class will have to be compiled and WSA
will have to be run again with the same config file.
To generate the service artifacts type: ant gen-service. The source code
for the service-artifacts will be placed in the build/src/service directory
using the package name oracle.demo.topdowndoclit.service.
Examine the type-mapping.xml file. This file is
used to instruct WSA how to map types to package name. A namespace URI is
mapped to a specific package name. Notice that this example maps its types
to the package oracle.demo.topdowndoclit.types. So for service artifacts
the types are generated in build/src/service/oracle/demo/topdowndoclit/types.
In this step you will compile the implementation classes and regenerate
the EAR file that will now contain both service artifacts and the implementation
class.
Examine the file DocLitLoggerImpl.java under src/service/oracle/demo/topdowndoclit/service
notice that the class implements LoggingFacilityLogPortType which is a service
artifact and thus generated by the tool. Before the first step there were
no generated files so compiling this class would have failed. Now that you
have already ran the gen-service task you are ready to compile the class
and update the EAR. To update the implementation type: ant update-impl.
The service is now ready to be deployed.
Examine the doclit_topdown.ear in the build directory. It should contain
a WAR file named doclit_topdown-web.war. This WAR file contains all the
service artifacts, implementation classes, as well as the web deployment
descriptor (web.xml) and the jaxrpc deployment descriptor (jaxrpc-ri-runtime.xml).
To deploy this ear to a running instance of oc4j type: ant deploy-demo.
After this task is complete you can check your application by typing in
the following url: http://localhost:8888/doclit_topdown/doclit_topdown
into a web browser. You will not be able to invoke the methods because this
is a document literal service. You can view the wsdl for this service by
pointing your browser to
http://localhost:8888/doclit_topdown/doclit_topdown?WSDL.
In this step you will generate the stubs for the service. A client application uses a stub to invoke operations on a remote service. Examine the file client-config.xml. This is the configuration file that the WebServices Assembler (WSA) tool uses to generate the stubs. To generate the stubs type: ant gen-stubs. The source for the stubs will be placed in build/src/client.
You are now ready to run the client. Examine the file DocLitLoggerClient.java in src/client/oracle/demo/topdowndoclit/ . Notice that this class uses the stubs to set an endpoint address and to invoke methods on the remote service. To run the client type: ant run-demo. You should see some sample output.