Oracle® Application Server Web Services Developer's Guide 10g (10.1.3.1.0) Part Number B28974-01 |
|
|
View PDF |
This chapter describes the functionality provided by the WebServicesAssembler tool.
Default Algorithms to Map Between Target WSDL Namespaces and Java Package Names
How to Assign Multiple Web Services to an EAR or WAR Archive
The WebServicesAssembler tool assists in assembling Oracle Application Server Web Services. It enables you to generate the artifacts required to develop and deploy Web services, regardless of whether you are creating the service top down or bottom up. The WebServicesAssembler can also be invoked to create Web service client objects based on a WSDL.
Support for Top Down Web Service Generation
In the top down case, you provide WebServicesAssembler with a WSDL and it creates the service endpoint interfaces. You can then fill in the implementation for the service for any required architecture, such as Java classes.
See Also: Chapter 6, "Assembling a Web Service from WSDL" for an example of top down Web service assembly that uses WebServicesAssembler. |
Support for Bottom Up Web Service Generation
In the bottom up case, you start with existing business logic, such as Java classes, Enterprise Java Beans (EJBs), CORBA objects, JMS queues, or database artifacts such as PL/SQL procedures. WebServicesAssembler uses these artifacts to assemble a WSDL, a mapping file, and the necessary deployment descriptors.
See Also: See the following chapters for examples of bottom up Web service assembly that use WebServicesAssembler: |
Support for XML Schema-Driven Web Service Generation
In the schema-driven case, you start with an XML schema and generate Java beans. Once you have the Java beans, you write the interface that uses the beans as arguments and use the bottom up paradigm to generate the WSDL, mapping file and deployment descriptors.
While you could use JAX-B or Toplink to generate beans from XML schemas, you could also use WebServicesAssembler or Ant tasks.
See Also: "Using Custom Serialization in Schema-Driven Web Service Development" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on using Ant tasks or WebServicesAssembler to generate a Web service from a schema. |
Support for Deployment
Although the OC4J container handles deployment, the WebServicesAssembler tool assists you by ensuring that the application archives it generates are properly prepared for deployment. WebServicesAssembler handles the generation of all relevant deployment descriptors and maps proprietary configuration needed by the applications into Oracle specific deployment files. Applications based on Java classes or EJB 2.1 are deployable across different containers. These Web services are in a J2EE standard deployable form and adhere to industry standards, such as the JAX-RPC, Enterprise Web Services 1.1, and Web Services-Interoperability (WS-I) specifications.
Support for Command Line Invocation and Ant Tasks
The WebServicesAssembler tool can be invoked either on the command line or by Ant tasks. WebServicesAssembler allows you flexibility in how you assemble your Web service. You can break the assembly process into a number of steps that let you more closely control how the Web service is created. For example, you can perform the following tasks.
Use another mechanism to create deployment descriptors
To do this, WebServicesAssembler provides command line arguments to add and delete services from deployment descriptors. This means that you can start with a set of hand-coded deployment descriptors that contain information that WebServicesAssembler does not generate. You can then use WebServicesAssembler to append information to these descriptors.
Control when artifacts are compiled and which classpath to use
Control when artifacts are packaged into an archive
Control the content of the archive
Create platform-independent build files
The WebServicesAssembler tool supports a number of commands. When you invoke WebServicesAssembler, only one command can appear on the command line.
A typical command line has the following syntax.
java -jar [OC4J_HOME]/webservices/lib/wsa.jar -[command] -[argument name][argument value]...
In this example, OC4J_HOME
is where OC4J was installed and wsa.jar
is the name of the WebServicesAssembler JAR file. Note the following command line syntax rules.
A command must be specified first on the command line.
Commands and arguments can be preceded with a dash "-", however, it is not required.
A space must separate an argument name from its value.
All argument names are case-sensitive when used in Ant tasks. They are not case-sensitive when used on the command line.
If a white space is required in an argument value, the value must be escaped.
For example, on Windows and Linux, white space must be double-quoted. Other operating systems may require a different way to pass white space as parameters to a Java executable.
All arguments that are used after the command can be placed in any order.
Typically, an argument can appear only once on the command line. Exceptions to this rule are noted in the individual argument descriptions.
To call WebServicesAssembler commands from Ant tasks, you may need to make some changes and additions to your installation of Ant.
See Also: "How to Set Up Ant for WebServicesAssembler" for a description of the changes and additions needed to call Ant tasks. |
This section describes the commands available for the WebServicesAssembler tool. The commands are organized into the following categories based on the functionality they provide.
Web Service Assembly Commands—assemble Web services. These commands create all of the files necessary to create a deployable archive such as a WAR, an EAR, or an EJB JAR.
WSDL Management Commands—perform actions on a WSDL, such as generate a WSDL for bottom up development, manage its contents and location, and determine whether it can be processed by WebServicesAssembler.
Java Generation Commands—generate code to create a Java interface from a WSDL, a proxy/stub, or JAX-RPC value type classes.
Deployment Descriptor Generation Commands—generate deployment descriptors for EARs, WARs, or EJB JARs.
Maintenance Commands—return a short description of WebServicesAssembler commands and the version number of the tool.
The following commands can be used to assemble a Web service.
aqAssemble—Assembles a Web service from a Advanced Queue in the database
assemble—Assembles a Web service from Java classes and annotated Java classes. (See Chapter 11, "Assembling Web Services with Annotations" for more information on using J2SE 5.0 Web Services Annotations.)
corbaAssemble—Assembles a Web service endpoint from a CORBA servant object
dbJavaAssemble—Assembles Web services from a Java class in a database
ejbAssemble—Assembles an EJB as a Web service
jmsAssemble—Assembles a JMS Endpoint Web service
plsqlAssemble—Assembles a Web service from a PL/SQL package
sqlAssembles—Assembles a Web service from SQL queries and DML statements
topDownAssemble—Assembles Web service classes and deployment descriptors from a WSDL specification
These commands share the following functionality and behavior:
Each of the *Assemble
commands creates all of the files required for a deployable archive.
Each of the *Assemble
commands, except topDownAssemble
, calls the assemble
command after they generate a Java class.
The files created by the *Assemble
commands are placed in the staging directory structure under the directory specified by the output
argument.
See Figure 18-1 for an illustration of the staging directory structure created by the *Assemble
commands.
The names and contents of the ear
and war
directories are affected by the values you provide for the ear
and war
arguments.
See "ear" and "war" for more information on these arguments.
The output of each of the *Assemble
commands, except ejbAssemble
, is an EAR and a WAR file, and an optional directory that contains the contents of a WAR that can be deployed into an OC4J instance.
The contents of the classpath are not copied to the archive. If you specify the classpath
or input
arguments to any of the *Assemble
commands, you must be sure that the classes found in the classpath are also available in the server.
You can add files to an EAR or WAR file before it is archived by the *Assemble
commands.
See "How to Add Files to an Archive" for more information on this topic.
Figure 18-1 illustrates the staging directory structure created by the *Assemble
commands. Beneath the specified output directory, the commands create three subdirectories: ear
, src
, and war
.
The ear
subdirectory contains the contents of the generated EAR file. It also contains a META-INF
subdirectory that contains the application.xml
file.
The src
subdirectory contains the generated source files. It also contains a proxy
subdirectory that contains the Java proxy files. If the Web Service is assembled from a WSDL (top down), src
also contains subdirectory with a skeleton of the generated service endpoint interface and value type classes.
The war
subdirectory contains the contents of the generated WAR file. This subdirectory also contains a WEB-INF
subdirectory. WEB-INF
contains the mapping files and the standard and Oracle proprietary deployment descriptors. These files include the web-service_name_java_wsdl_mapping.xml
, web.xml
, oracle-webservices.xml
and webservices.xml
files.
WEB-INF
also contains the classes
and wsdl
subdirectories. The classes
subdirectory contains the implementation classes. The wsdl
subdirectory contains the Web service's WSDL file.
Note: WebServicesAssembler does not remove files from thewar and ear staging directories by default. If you use the same output directory for multiple invocations of WebServicesAssembler, then you may find extra, unwanted files in the WAR and EAR archives. If you want to avoid this behavior, do one of the following:
|
Figure 18-1 Staging Directory Structure Created by the *Assemble Commands
Use the aqAssemble
command to generate Web services from an advanced queue in the database. To use this command, you must connect to a database.
The aqAssemble
command can also add WSIF bindings for an advanced queue to the WSDL. Use the wsifDbBinding
argument to add WSIF bindings to the WSDL when you are exposing a database resource as a Web service. You must specify the className
of the resource's Oracle JPublisher-generated Java class and a database connection.
See Also:
|
Command Line Example:
java -jar wsa.jar -aqAssemble -dbUser scott/tiger -sql ToyQueue -dbConnection jdbc:oracle:thin:@dsunrde22:1521:sqlj -dataSource jdbc/OracleManagedDS -appName query
Ant Task Example:
<oracle:aqAssemble dbUser="scott/tiger" sql="ToyQueue" dbConnection="jdbc:oracle:thin:@dsunrde22:1521:sqlj" dataSource="jdbc/OracleManagedDS" appName="query" />
Required Arguments:
To use the aqAssemble
command, you must specify the following arguments.
Database Assembly Arguments: sql
You must also connect to the database. To do this, use one of the following combinations of arguments.
All Arguments:
The following list identifies all of the arguments that can be used with the aqAssemble
command.
Database Assembly Arguments: aqConnectionFactoryLocation, aqConnectionLocation, dataSource, dbConnection, dbUser, jpubProp, sql (required), sqlTimeout, sysUser, useDataSource, wsifDbBinding, wsifDbPort
For more information on these arguments, see "Database Assembly Arguments".
Deployment Descriptor Arguments: appendToExistingDDs, context, ddFileName, uri
For more information on these arguments, see "Deployment Descriptor Arguments".
General Assembly Arguments: appName, debug, ear, emptySoapAction, help, interfaceName, mappingFileName, output, packageName, portName, restSupport, schema, serviceName, useDimeEncoding, war
For more information on these arguments see, "General Web Services Assembly Arguments".
Java Generation Arguments: valueTypeClassName
For more information on this argument, see "Java Generation Arguments".
Message Format Arguments: style, use
For more information on these arguments, see "Message Format Arguments".
Session Arguments: timeout
For more information on this argument, see "Session Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: createOneWayOperations, genQos, qualifiedElementForm, soapVersion, targetNamespace, typeNamespace
For more information on these arguments, see "WSDL Management Arguments".
Ant Task Support:
<proxy>
tags. For more information, see "How to Configure Proxy Generation in an Ant Task".
<port>
tags. In the <port>
tag, aqAssemble
can use these arguments: bindingName, name
(same as portName
), portName, sendConnectionFactoryLocation, sendQueueLocation, soapVersion, and uri. For more information, see "How to Configure a Port in an Ant Task".
<handler>
tags. For more information, see "How to Configure Handlers in an Ant Task".
Use the assemble
command to generate a Web service bottom up. The command creates all of the files required to create a deployable archive. These files include the proprietary oracle-webservices.xml
deployment descriptor. The command can generate stateless Web services whether the transport mechanism is HTTP or JMS.
To find the Java implementation class, you must specify an input
or classpath
argument. If you specify either of these arguments, you must be sure that the classes found in the classpath are also available in the server. This is because the contents of the classpath are not copied to the archive.
Assembling WSIF Bindings into the WSDL
In addition to generating a Web service, the assemble
command can also add WSIF bindings to the WSDL. Use the wsifJavaBinding
argument to add WSIF bindings to the WSDL when you are exposing a Java class as a Web service. You must also specify the Java class with the className
argument.
See Also:
|
Assembling a Web Service with J2SE 5.0 Annotations
If you are using the assemble
command to assemble a Web service from Java classes that contain J2SE 5.0 Annotations, then use the className
argument to identify the implementation class. The @WebService
annotation must be present on the class declaration.
J2SE 5.0 annotations require a class name because annotations can appear in either the interface or the implementation class. If the annotations appear only in the interface, WebServicesAssembler can obtain them through its referenced implementation class. If the implementation class also contains annotations, WebServicesAssembler will process them.
The following example illustrates the assemble
command being used to generate a Web service from a Java class that contains J2SE 5.0 annotations. The className
argument specifies the com.mycompany.HelloImpl
class.
java -jar wsa.jar assemble -appName myService -className com.mycompany.HelloImpl -output wsdl
If you want WebServicesAssembler to process only the annotations in the interface, then enter the @WebService
annotation with the serviceEndpointInterface
property in the implementation class file. J2SE 5.0 annotations will expect all remaining annotations to appear in the service endpoint interface class. For example, if you enter the following annotation in the implementation class file, then WebServicesAssembler will process only the annotations in the demo.myInterface
interface.
@WebService(serviceEndpointInterface="demo.myInterface")
See Also: Chapter 11, "Assembling Web Services with Annotations" for more information on using J2SE 5.0 Annotations to assemble a Web service. |
The following command line and Ant task examples demonstrate how to use the assemble
command to generate a Web service bottom up. The command will create an EAR file named build/myService.ear
.
Command Line Example:
java -jar wsa.jar -assemble -input myservice.jar -className com.mycompany.HelloImpl -interfaceName com.myCompany.myService.Hello -output build -appName myService
Ant Task Example:
<oracle:assemble appName="myService" output="build" input="myservice.jar > <oracle:porttype interfaceName="com.myCompany.myService.Hello" className="com.mycompany.HelloImpl"/> </oracle:assemble>
Required Arguments:
To use the assemble
command, you must specify the following arguments.
General Assembly Arguments: className
All Arguments
The following list identifies all of the arguments that can be used with the assemble
command.
Deployment Descriptor Arguments: appendToExistingDDs, context, ddFileName, uri
For more information on these arguments, see "Deployment Descriptor Arguments".
General Assembly Arguments: appName, bindingName, className (required), classpath, debug, ear, emptySoapAction, help, input, interfaceFileName, interfaceName, mappingFileName, output, portName, portTypeName, restSupport, schema, serviceName, strictJaxrpcValidation, useDimeEncoding, war
For more information on these arguments see, "General Web Services Assembly Arguments".
Java Generation Arguments: valueTypeClassName, wsifJavaBinding
For more information on these arguments, see "Java Generation Arguments".
JMS Assembly Arguments: sendConnectionFactoryLocation, sendQueueLocation
For more information on these argument, see "JMS Assembly Arguments".
Message Format Arguments: mtomSupport, style, use
For more information on these arguments, see "Message Format Arguments".
Session Arguments: callScope, recoverable, session, timeout
For more information on these arguments, see "Session Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: createOneWayOperations, genQos, qualifiedElementForm, soapVersion, targetNamespace, typeNamespace
For more information on these arguments, see "WSDL Management Arguments".
Ant Task Supports:
<proxy>
tags. For more information, see "How to Configure Proxy Generation in an Ant Task".
<port>
tags. In the <port>
tag, assemble
can use these arguments: bindingName, name
(same as portName
), portName, sendConnectionFactoryLocation, sendQueueLocation, soapVersion, and uri. For more information, see "How to Configure a Port in an Ant Task".
<porttype>
tags. For more information, see "How to Configure a Port Type in an Ant Task".
<handler>
tags. For more information, see "How to Configure Handlers in an Ant Task".
tags to specify WSIF bindings for multiple ports. For more information, see "Configuring a WSIF Endpoint for Multiple Java Ports" in the Oracle Application Server Advanced Web Services Developer's Guide.
Use the corbaAssemble
command to expose a CORBA servant object as a Web service. The command takes a CORBA IDL file and CORBA naming properties as input. It outputs all of the files required to create a deployable archive.
Internally, WebServicesAssembler will invoke the IDL-to-Java compiler (idlj
) that can be found in the environment. The JDK bin
directory must be part of the path
environment variable. WebServicesAssembler uses the IDL-to-Java compiler to compile the IDL file into Java classes.
Command Line Example
java -jar wsa.jar -corbaAssemble -idlInterfaceName oraclecorba.Hello -corbanameURL corbaname::corba.orbd.host:1050#oracle.corba/Hello -idlFile ./Hello.idl -uri /corba_hello -output dist -context corba_hello -targetNamespace http://oracle.j2ee.ws/corba/Hello -typeNamespace http://oracle.j2ee.ws/corba/Hello/types -serviceName Corba_hello -appName corba_hello -style rpc -use literal
Ant Task Example:
<oracle:corbaAssemble idlInterfaceName="oraclecorba.Hello" corbanameURL="corbaname::corba.orbd.host:1050#oracle.corba/Hello" idlFile="./Hello.idl" output="dist" context="corba_hello" targetNamespace="http://oracle.j2ee.ws/corba/Hello" typeNamespace="http://oracle.j2ee.ws/corba/Hello/types" serviceName="Corba_hello" appName="corba_hello" style="rpc" use="literal" > <oracle:port uri="/corba_hello" /> </oracle:corbaAssemble>
Required Arguments:
To use the corbaAssemble
command, you must specify the following arguments.
CORBA Assembly Arguments: idlInterfaceName
All Arguments:
The following list identifies all of the arguments that can be used with the corbaAssemble
command.
CORBA Assembly Arguments: corbanameURL, corbaObjectPath, idlFile, idlInterfaceName (required), idljPath, ORBInitialHost, ORBInitialPort, ORBInitRef
For more information on these arguments, see "CORBA Assembly Arguments".
Deployment Descriptor Arguments: appendToExistingDDs, context, ddFileName, uri
For more information on these arguments, see "Deployment Descriptor Arguments".
General Assembly Arguments: appName, bindingName, className, classpath, debug, ear, emptySoapAction, help, mappingFileName, output, packageName, portName, portTypeName, restSupport, schema, serviceName, useDimeEncoding, war
For more information on these arguments see, "General Web Services Assembly Arguments".
JMS Assembly Arguments: sendConnectionFactoryLocation, sendQueueLocation
For more information on these arguments, see "JMS Assembly Arguments".
Message Format Arguments: style, use
For more information on these arguments, see "Message Format Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: createOneWayOperations, genQos, qualifiedElementForm, soapVersion, targetNamespace, typeNamespace
For more information on these arguments, see "WSDL Management Arguments".
Ant Task Support:
<proxy>
tags. For more information, see "How to Configure Proxy Generation in an Ant Task".
<port>
tags. In the <port>
tag, corbaAssemble
can use these arguments: bindingName, name
(same as portName
), portName, sendConnectionFactoryLocation, sendQueueLocation, soapVersion, and uri. For more information, see "How to Configure a Port in an Ant Task".
<handler>
tags. For more information, see "How to Configure Handlers in an Ant Task".
Use the dbJavaAssemble
command to generate Web services from a Java class inside the Java VM in an Oracle database. To use this command, you must connect to a database.
The dbJavaAssemble
command can also add WSIF bindings for a Java class inside the Java VM to the WSDL. Use the wsifDbBinding
argument to add WSIF bindings to the WSDL when you are exposing a database resource as a Web service. You must specify the className
of the resource's Oracle JPublisher-generated Java class and a database connection.
See Also:
|
Command Line Example:
java -jar wsa.jar -dbJavaAssemble -dbJavaClassName oracle.sqlj.checker.JdbcVersion -dbUser scott/tiger -dbConnection jdbc:oracle:thin:@dsunrde22:1521:sqlj -dataSource jdbc/OracleManagedDS -appName javacallin
Ant Task Example:
<oracle:dbJavaAssemble dbUser="scott/tiger" dbJavaClassName="oracle.sqlj.checker.JdbcVersion" dbConnection="jdbc:oracle:thin:@dsunrde22:1521:sqlj" dataSource="jdbc/OracleManagedDS" appName="javacallin" />
Required Arguments:
To use the dbJavaAssemble
command, you must specify the following arguments.
Database Assembly Arguments: dbJavaClassName
The dbJavaClassName
argument specifies the Java class in the database that is to be published as a Web service.
You must also connect to the database. To do this, use one of the following combinations of arguments:
All Arguments:
The following list identifies all of the arguments that can be used with the dbJavaAssemble
command.
Database Assembly Arguments: dataSource, dbConnection, dbJavaClassName (required), dbUser, jpubProp, sysUser, useDataSource, wsifDbBinding, wsifDbPort
For more information on these arguments, see "Database Assembly Arguments".
Deployment Descriptor Arguments: appendToExistingDDs, context, ddFileName, uri
For more information on these arguments, see "Deployment Descriptor Arguments".
General Assembly Arguments: appName, className, classpath, debug, ear, emptySoapAction, help, interfaceName, mappingFileName, output, packageName, portName, restSupport, schema, serviceName, useDimeEncoding, war
For more information on these arguments see, "General Web Services Assembly Arguments".
Java Generation Arguments: valueTypeClassName
For more information on this argument, see "Java Generation Arguments".
Message Format Arguments: style, use
For more information on these arguments, see "Message Format Arguments".
Session Arguments: timeout
For more information on this argument, see "Session Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: createOneWayOperations, genQos, qualifiedElementForm, soapVersion, targetNamespace, typeNamespace
For more information on these arguments, see "WSDL Management Arguments".
Ant Task Support:
<proxy>
tags. For more information, see "How to Configure Proxy Generation in an Ant Task".
<port>
tags. In the <port>
tag, dbJavaAssemble
can use these arguments: bindingName, portName (or name
), sendConnectionFactoryLocation, sendQueueLocation, soapVersion, and uri. For more information, see "How to Configure a Port in an Ant Task".
<handler>
tags. For more information, see "How to Configure Handlers in an Ant Task".
Use the ejbAssemble
command to create an EAR or EJB JAR that can expose an EJB as a Web service. You must specify a valid version 2.1 EJB JAR as input; the system will create a WSDL and the proprietary oracle-webservices.xml
deployment descriptor.
By default, this command creates an EAR file that contains a version 2.1 EJB file that can be deployed directly. The oracle-webservices.xml
file specifies the context and URL pattern that can be used to access the EJB as a Web service.
If you do not want to deploy the EJB as an EAR file, you can create an EJB JAR file instead. For example, this enables you to deploy the EJB as a JAR file to a J2EE container, or to use other J2EE application deployment tools, such as Ant. To save the EJB as a JAR file, specify a directory for the ear
argument.
Assembling WSIF Bindings into the WSDL
The ejbAssemble
command can also add WSIF bindings to the WSDL. Use the wsifEjbBinding
argument to add WSIF bindings when you are exposing an EJB as a Web service. You must specify the EJB's home interface in the className
argument and its JNDI name in the jndiName
argument.
Note: You cannot use theejbAssemble command or WebServicesAssembler to assemble Web services from version 3.0 EJBs. To do this, you must use J2SE 5.0 Annotations. For more information, see "Steps to Use Annotations to Assemble a Web Service from a Version 3.0 EJB". |
See Also:
|
The following command line and Ant task examples create the EAR file build/myService.ear
.
Command Line Example:
java -jar wsa.jar -ejbAssemble -output build -input myEjb.jar -ejbName myEjb -appName myService
Ant Task Example:
<oracle:ejbAssemble output="build" input="myEjb.jar" ejbName="myEjb" appName="myService" />
Required Arguments:
To use the ejbAssemble
command, you must specify the following arguments.
All Arguments:
The following list identifies all of the arguments that can be used with the ejbAssemble
command.
Deployment Descriptor Arguments: appendToExistingDDs, context, ddFileName, uri
For more information on these arguments, see "Deployment Descriptor Arguments".
General Assembly Arguments: appName, bindingName, className, classpath, debug, ear, ejbName (required), emptySoapAction, help, initialContextFactory, input (required), interfaceName, jndiName, jndiProviderURL, mappingFileName, output, portName, portTypeName, restSupport, schema, serviceName, strictJaxrpcValidation, useDimeEncoding
For more information on these arguments see, "General Web Services Assembly Arguments".
Java Generation Arguments: valueTypeClassName, wsifEjbBinding
For more information on these arguments, see "Java Generation Arguments".
JMS Assembly Arguments: sendConnectionFactoryLocation, sendQueueLocation
For more information on these arguments, see "JMS Assembly Arguments".
Message Format Arguments: style, use
For more information on these arguments, see "Message Format Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: createOneWayOperations, genQos, qualifiedElementForm, soapVersion, targetNamespace, typeNamespace
For more information on these arguments, see "WSDL Management Arguments".
Additional Ant Support:
<proxy>
tags. For more information, see "How to Configure Proxy Generation in an Ant Task".
<port>
tags. In the <port>
tag, ejbAssemble
can use these arguments: bindingName, name
(same as portName
), portName, sendConnectionFactoryLocation, sendQueueLocation, soapVersion, and uri. For more information, see "How to Configure a Port in an Ant Task".
<handler>
tags. For more information, see "How to Configure Handlers in an Ant Task".
tags to specify WSIF bindings for multiple ports. For more information, see "Configuring a WSIF Endpoint for Multiple EJB Ports" in the Oracle Application Server Advanced Web Services Developer's Guide.
Use the jmsAssemble
command to expose a JMS destination (queue or topic) as a Web service. JMS Web services have two types of operations: send and receive. The send operation sends a message to the JMS destination. The receive operation retrieves a message from the destination. Some of the JMS message properties (for example, correlation ID) can be exposed as SOAP headers.
See Also: Chapter 9, "Assembling Web Services with JMS Destinations" provides more information on using the |
Command Line Example:
java -jar wsa.jar -jmsAssemble -sendConnectionFactoryLocation jms/ws/mdb/theQueueConnectionFactory -sendQueueLocation jms/ws/mdb/theQueue -replyToConnectionFactoryLocation jms/ws/mdb/logQueueConnectionFactory -replyToQueueLocation jms/ws/mdb/logQueue -linkReceiveWithReplyTo true -targetNamespace http://oracle.j2ee.ws/jms-doc -typeNamespace http://oracle.j2ee.ws/jms-doc/types -serviceName JmsService -appName jms_service -context jms_service -input ./demo/build/mdb_service.jar -uri JmsService -output ./demo/dist
Ant Task Example:
<oracle:jmsAssemble linkReceiveWithReplyTo="true" targetNamespace="http://oracle.j2ee.ws/jms-doc" typeNamespace="http://oracle.j2ee.ws/jms-doc/types" serviceName="JmsService" appName="jms_service" context="jms_service" input="./demo/build/mdb_service.jar" output="./demo/dist" > <oracle:port uri="JmsService" sendConnectionFactoryLocation="jms/ws/mdb/theQueueConnectionFactory" sendQueueLocation="jms/ws/mdb/theQueue" replyToConnectionFactoryLocation="jms/ws/mdb/logQueueConnectionFactory" replyToQueueLocation="jms/ws/mdb/logQueue"/> </oracle:jmsAssemble>
Required Arguments:
To use the jmsAssemble
command, you must specify the following arguments.
JMS Assembly Arguments: either replyToConnectionFactoryLocation or sendConnectionFactoryLocation
All Arguments:
The following list identifies all of the arguments that can be used with the jmsAssemble
command.
Deployment Descriptor Arguments: appendToExistingDDs, context, ddFileName, uri
For more information on these arguments, see "Deployment Descriptor Arguments".
General Assembly Arguments: appName, bindingName, debug, ear, emptySoapAction, help, input, output, portName, portTypeName, serviceName, useDimeEncoding, war
For more information on these arguments see, "General Web Services Assembly Arguments".
JMS Assembly Arguments: deliveryMode, genJmsPropertyHeader, jmsTypeHeader, linkReceiveWithReplyTo, payloadBindingClassName, priority, receiveConnectionFactoryLocation, receiveQueueLocation, receiveTimeout, receiveTopicLocation, replyToConnectionFactoryLocation, replyToQueueLocation, replyToTopicLocation, sendConnectionFactoryLocation, sendQueueLocation, sendTopicLocation, timeToLive, topicDurableSubscriptionName
For more information on these arguments, see "JMS Assembly Arguments".
WSDL Management Arguments: createOneWayOperations, genQos, qualifiedElementForm, soapVersion, targetNamespace, typeNamespace
For more information on these arguments, see "WSDL Management Arguments".
Ant Task Supports:
<proxy>
tags. For more information, see "How to Configure Proxy Generation in an Ant Task".
<port>
tags. In the <port>
tag, jmsAssemble
can use these arguments: bindingName, name
(same as portName
), portName, sendConnectionFactoryLocation, sendQueueLocation, soapVersion, and uri. For more information, see "How to Configure a Port in an Ant Task".
<handler>
tags. For more information, see "How to Configure Handlers in an Ant Task".
Use the plsqlAssemble
command to generate Web services from a PL/SQL package containing stored procedures and functions. To use this command, you must connect to a database.
See Also:
|
Assembling WSIF Bindings into the WSDL
The plsqlAssemble
command can also add WSIF bindings for a PL/SQL package to the WSDL. Use the wsifDbBinding
argument to add WSIF bindings to the WSDL when you are exposing a database resource as a Web service. You must specify the className
of the resource's Oracle JPublisher-generated Java class and a database connection.
See Also: "Configuring a WSIF Endpoint for Database Resources" in the Oracle Application Server Advanced Web Services Developer's Guide provides more information on adding bindings for database resources to the WSDL. |
Command Line Example:
java -jar wsa.jar -plsqlAssemble -appName query -dbUser scott/tiger -sql Company -dbConnection jdbc:oracle:thin:@dsunrde22:1521:sqlj -dataSource jdbc/OracleManagedDS
Ant Task Example:
<oracle:plsqlAssemble dbUser="scott/tiger" appName="query" sql="Company" dbConnection="jdbc:oracle:thin:@dsunrde22:1521:sqlj" dataSource="jdbc/OracleManagedDS" />
Required Arguments:
To use the plsqlAssemble
command, you must specify the following arguments.
Database Assembly Arguments: sql
The sql
argument specifies the name of the PL/SQL package that is to be published as a Web service.
You must also connect to the database. To do this, use one of the following combinations of arguments.
All Arguments:
The following list identifies all of the arguments that can be used with the plsqlAssemble
command.
Database Assembly Arguments: dataSource, dbConnection, dbUser, jpubProp, sql, sysUser, useDataSource, wsifDbBinding, wsifDbPort
For more information on these arguments, see "Database Assembly Arguments".
Deployment Descriptor Arguments: appendToExistingDDs, context, ddFileName, uri
For more information on these arguments, see "Deployment Descriptor Arguments".
General Assembly Arguments: appName, className, classpath, debug, ear, emptySoapAction, help, interfaceName, mappingFileName, output, packageName, portName, restSupport, schema, serviceName, useDimeEncoding, war
For more information on these arguments see, "General Web Services Assembly Arguments".
Java Generation Arguments: valueTypeClassName
For more information on this argument, see "Java Generation Arguments".
Message Format Arguments: style, use
For more information on these arguments, see "Message Format Arguments".
Session Arguments: timeout
For more information on this argument, see "Session Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: createOneWayOperations, genQos, qualifiedElementForm, soapVersion, targetNamespace, typeNamespace
For more information on these arguments, see "WSDL Management Arguments".
Ant Task Support:
<proxy>
tags. For more information, see "How to Configure Proxy Generation in an Ant Task".
<port>
tags. In the <port>
tag, plsqlAssemble
can use these arguments: bindingName, name
(same as portName
), portName, sendConnectionFactoryLocation, sendQueueLocation, soapVersion, and uri. For more information, see "How to Configure a Port in an Ant Task".
<handler>
tags. For more information, see "How to Configure Handlers in an Ant Task".
Use the sqlAssemble
command to generate Web services from SQL statements, including SQL queries and DMLs (Data Manipulation Language). To use this command, you must connect to a database.
See Also:
|
Adding WSIF Bindings to the WSDL
The sqlAssemble
command can also add WSIF bindings for SQL queries to the WSDL. Use the wsifDbBinding
argument to add WSIF bindings to the WSDL when you are exposing a database resource as a Web service. You must specify the className
of the resource's Oracle JPublisher-generated Java class and a database connection.
See Also: "Configuring a WSIF Endpoint for Database Resources" in the Oracle Application Server Advanced Web Services Developer's Guide provides more information on adding bindings for database resources to the WSDL. |
The following command line and Ant task examples establish a database connection and run two SQL commands.
Command Line Example:
java -jar wsa.jar -sqlAssemble -dbUser scott/tiger -sqlstatement "getEmp=select ename, sal from emp where empno=:{id NUMBER}" -sqlstatement "getEmpBySal=select ename, sal from emp where sal>:{mysal NUMBER}" -dbConnection jdbc:oracle:thin:@dsunrde22:1521:sqlj -dataSource jdbc/OracleManagedDS
Ant Task Example:
<oracle:sqlAssemble dbUser="scott/tiger" dbConnection="jdbc:oracle:thin:@dsunrde22:1521:sqlj" dataSource="jdbc/OracleManagedDS" appName="query"> <sqlstatement value="getEmp=select ename, sal from emp where empno=:{id NUMBER}"/> <sqlstatement value="getEmpBySal=select ename, sal from emp where sal>:{mysal NUMBER}"/> </oracle:sqlAssemble>
Required Arguments:
To use the sqlAssemble
command, you must specify the following arguments.
Database Assembly Arguments: sqlstatement
You must also connect to the database. To do this, use one of the following combinations of arguments.
All Arguments:
The following list identifies all of the arguments that can be used with the sqlAssemble
command.
Database Assembly Arguments: dataSource, dbConnection, dbUser, jpubProp, sql, sqlstatement, sysUser, useDataSource, wsifDbBinding, wsifDbPort
For more information on these arguments, see "Database Assembly Arguments".
Deployment Descriptor Arguments: appendToExistingDDs, context, ddFileName, uri
For more information on these arguments, see "Deployment Descriptor Arguments".
General Assembly Arguments: appName, className, classpath, debug, ear, emptySoapAction, help, interfaceName, mappingFileName, output, packageName, portName, restSupport, schema, serviceName, useDimeEncoding, war
For more information on these arguments see, "General Web Services Assembly Arguments".
Java Generation Arguments: valueTypeClassName
For more information on this argument, see "Java Generation Arguments".
Message Format Arguments: style, use
For more information on these arguments, see "Message Format Arguments".
Session Arguments: timeout
For more information on this argument, see "Session Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: createOneWayOperations, genQos, qualifiedElementForm, soapVersion, targetNamespace, typeNamespace
For more information on these arguments, see "WSDL Management Arguments".
Ant Task Support:
<proxy>
tags. For more information, see "How to Configure Proxy Generation in an Ant Task".
<port>
tags. In the <port>
tag, sqlAssemble
can use these arguments: bindingName, name
(same as portName
), portName, sendConnectionFactoryLocation, sendQueueLocation, soapVersion, and uri. For more information, see "How to Configure a Port in an Ant Task".
<handler>
tags. For more information, see "How to Configure Handlers in an Ant Task".
Use the topDownAssemble
command to create the required classes and deployment descriptors for a Web service based on a WSDL description. The files can be stored in either an EAR file, a WAR file, or a directory. You must specify a value for either the input
or classpath
arguments to allow for the proper loading of the specified implementation class.
This command is typically used with genInterface
to generate a Web service top down. If these commands are used together to generate a Web service, then they must share the same value for the unwrapParameters
argument.
Only one service element can be implemented. WebServicesAssembler enables you to generate the artifacts for only one service at a time. If more than one service is described in the WSDL, a command line argument, serviceName
, enables you to specify the service you want to use.
Note that if there is any conflict between the names of generated classes, then they will be resolved according to JAX-RPC rules as described in section 4.3.12, "Name Collisions" in the JAX-RPC specification. For more information, see "Resolving Name Collisions".
See Also: Chapter 6, "Assembling a Web Service from WSDL" provides more information on using the |
WSDL Limitations
The following list describes the limitations on WSDLs that can be consumed by WebServicesAssembler.
If the WSDL contains references to multiple port types, then the topDownAssemble
command must specify a <porttype>
tag for each port type.
National Language Support (also known as "NLS" or "Globalization Support") characters that occur in names in the WSDL, such as in the name of a service, port type, operation, binding or port, are not supported. This may also result in errors in the Web Services Test Page.
In top down Web service development, you cannot use WebServicesAssembler to change the message format. You can do this only by editing the WSDL.
The WSDL cannot contain multiple message formats. Remove any ports from the WSDL that reference a binding with a message format that you do not want to use.
WebServicesAssembler cannot consume WSDLs that contain the xsd:choice
or xsd:group
XML types. If you want to consume a WSDL that contains these XML types, set the WebServicesAssembler dataBinding
argument to false
and code the SOAPElement
so that the payload conforms to the schema definition in the WSDL file.
The following command line and Ant task create required classes and deployment descriptors for a Web service. It creates an EAR build/myService.ear.
The target of the input
argument should contain the implementation classes. These classes will be copied to the generated archive for you.
Command Line Example:
java -jar wsa.jar -topDownAssemble -output build -wsdl my.wsdl -input myClasses -className com.mycompany.HelloImpl -appName myService
Ant Task Example:
<oracle:topDownAssemble output="build" wsdl="my.wsdl" input="myClasses" appName="myService"> <porttype className="com.mycompany.HelloImpl"/> </oracle:topDownAssemble>
Required Arguments:
To use the topDownAssemble
command, you must specify the following arguments.
All Arguments:
The following list identifies all of the arguments that can be used with the topDownAssemble
command.
Deployment Descriptor Arguments: appendToExistingDDs, context, ddFileName, uri
For more information on these arguments, see "Deployment Descriptor Arguments".
General Assembly Arguments: appName, classFileName, className (required), classpath, debug, ear, emptySoapAction, help, input, interfaceName, mappingFileName, output, packageName, portName, restSupport, searchSchema, serviceName, useDimeEncoding, war
For more information on these arguments see, "General Web Services Assembly Arguments".
Java Generation Arguments: dataBinding, mapHeadersToParameters, overwriteBeans, unwrapParameters, valueTypePackagePrefix
For more information on these arguments, see "Java Generation Arguments".
Message Format Arguments: mtomSupport
For more information on this argument, see "Message Format Arguments".
WSDL Access Arguments: fetchWsdlImports, httpNonProxyHosts, httpProxyHost, httpProxyPort, wsdl (required)
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: wsdlTimeout
For more information on this argument, see "WSDL Management Arguments".
Additional Ant Support:
<proxy>
tags. For more information, see "How to Configure Proxy Generation in an Ant Task".
<port>
tags. In the <port>
tag, topDownAssemble
can use these arguments: name
(same as portName
), portName, and uri. For more information, see "How to Configure a Port in an Ant Task".
<porttype>
tags. For more information, see "How to Configure a Port Type in an Ant Task".
<handler>
tags. For more information, see "How to Configure Handlers in an Ant Task".
The following commands perform actions on a WSDL. The fetchWsdl
and genQosWsdl
commands are used in top down Web service development to manage the contents and location of the WSDL. The genWsdl
command is used to generate a WSDL for bottom up Web service development. The analyze
command can be used at any time to determine whether WebServicesAssembler supports the functionality described in the WSDL.
analyze—Determines whether WebServicesAssembler supports the functionality described in the WSDL
fetchWsdl—Copies the WSDL and its imports to an output directory
genConcreteWsdl—Creates a concrete WSDL by determining the message format from the abstract part of the WSDL
genQosWsdl—Inserts assertions about Quality of Service (capability assertions) into the WSDL
genWsdl—Generates a WSDL based on a Java interface
Use the analyze
command to confirm whether the WSDL can be processed by this version of the WebServicesAssembler. The analyze
command determines whether the specified WSDL can be used to generate a proxy or create an interface for top down assembly. The command also checks that the WSDL uses valid XML and whether it complies with the JAX-RPC requirements of OC4J.
This command returns a message if the WSDL cannot be processed.
Note: Theanalyze command does not check conformance to the Web Services Interoperability (WS-I) specification or general interoperability of your WSDL. You may want to use the WS-I Analyzer tool either directly, or from inside Oracle JDeveloper to check conformance. For more information on tools that you can use to check interoperability, see "Ensuring Interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide. |
The following command line and Ant task examples demonstrate using analyze
to see if the specified WSDL can be processed.
Command Line Example:
java -jar wsa.jar -analyze -wsdl myservice.wsdl
Ant Task Example:
<oracle:analyze wsdl="myservice.wsdl" />
Required Arguments:
To use the analyze
command, you must specify the following argument.
WSDL Access Arguments: wsdl
All Arguments:
The following list identifies all of the arguments that can be used with the analyze
command.
General Assembly Arguments: debug, help
For more information on these arguments, see "General Web Services Assembly Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort, wsdl (required)
For more information on this argument, see "WSDL Access Arguments".
WSDL Management Arguments: wsdlTimeout
For more information on this argument, see "WSDL Management Arguments".
Additional Ant Support:
None
Use the fetchWsdl
command in top down Web service generation to copy the base (or top level) WSDL file and all of its imported and included WSDLs and schemas into a specified output directory.
All of the WSDLs and schemas are downloaded into the same directory. Any naming conflicts are resolved by appending a number to the name of the file before the extension. For example, if three myschema.xsd
files are downloaded, they will be named myschema.xsd
, myschema1.xsd
, and myschema2.xsd
.
The following command line and Ant task examples will fetch the base WSDL specified by the URL, and any other WSDL fragments and schemas it imports. The results are then stored in the wsdl
directory.
Command Line Example:
java -jar wsa.jar -fetchWdsl -wsdl http://someserver/services/aservice?WSDL -output wsdl
Ant Task Example:
<oracle:fetchWsdl wsdl="http://someserver/services/aservice?WSDL" output="wsdl" />
Required Arguments:
To use the fetchWsdl
command, you must specify the following argument.
WSDL Access Arguments: wsdl
All Arguments:
The following list identifies all of the arguments that can be used with the fetchWsdl
command.
General Assembly Arguments: debug, help, output
For more information on these arguments, see "General Web Services Assembly Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort, wsdl (required)
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: wsdlTimeout
For more information on this argument, see "WSDL Management Arguments".
Additional Ant Support:
None
While an abstract WSDL is enough to define the API for a Web service, WebServicesAssembler needs a concrete WSDL to deploy a Web service or to generate client proxies that can communicate with a Web service.
If you have only an abstract WSDL, use the genConcreteWsdl
command. In top down Web service development, this command enables you to generate a concrete WSDL given an abstract WSDL. The command does this by analyzing the wsdl:portType
part of the WSDL and determining whether the bindings for the Web service (that is, the use
and style
values) should be document/literal or RPC/literal. The command writes these values into the binding
element of the WSDL, and saves it with the name determined by the value of the output
argument.
The following command line and Ant task examples take an abstract WSDL myAbstract.wsdl
as input and generate a concrete WSDL myConcrete.wsdl
in the outputDir
directory.
Command Line Example:
java -jar wsa.jar -genConcreteWsdl -output outputDir/myConcrete.wsdl -wsdl myAbstract.wsdl
Ant Task Example:
<oracle:genConcreteWsdl output="outputDir/myConcrete.wsdl" wsdl="myAbstract.wsdl" />
Required Arguments:
To use the genConcreteWsdl
command, you must specify the following argument.
WSDL Access Arguments: wsdl
All Arguments:
The following list identifies all of the arguments that can be used with the genConcreteWsdl
command.
Deployment Descriptor Arguments: ddFileName
For more information on this argument, see "Deployment Descriptor Arguments".
General Assembly Arguments: debug, help, output
For more information on these arguments, see "General Web Services Assembly Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort, importAbstractWsdl, wsdl (required)
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: singleService, wsdlTimeout
For more information on these arguments, see "WSDL Management Arguments".
Additional Ant Support:
None.
In top down Web service development, use the genQosWsdl
command to add capability assertions for security and reliability into a specified WSDL. Capability assertions are descriptions of Web service management policies that allow consumers of Web services to discover which management policies are enabled for the Web service.
Usually, the capability assertions are defined in the deployment descriptor. Use the ddFileName
argument to specify the file that contains the capability assertions and the wsdl
argument to specify the name of the WSDL into which they will be inserted. The output
argument specifies where the modified WSDL file will be stored. If you do not specify the output
argument, then the original WSDL will be overwritten.
See Also: "Working with Capability Assertions" in the Oracle Application Server Advanced Web Services Developer's Guide describes how capability assertions are derived and how they are inserted into the WSDL. |
The following command line and Ant task examples add assertions to my.wsdl
and store the results in the build
directory.
Command Line Example:
java -jar wsa.jar -genQosWsdl -wsdl my.wsdl -ddFileName oracle-webservices.xml -output build
Ant Task Example:
<oracle:genQosWsdl wsdl="my.wsdl" ddFileName="oracle-webservices.xml" output="build" />
Required Arguments:
To use the genQosWsdl
command, you must specify the following arguments.
Deployment Descriptor Arguments: ddFileName
WSDL Management Arguments: wsdl
All Arguments:
The following list identifies all of the arguments that can be used with the genQosWsdl
command.
Deployment Descriptor Arguments: ddFileName (required)
For more information on this argument, see "Deployment Descriptor Arguments".
General Assembly Arguments: debug, help, output
For more information on these arguments see, "General Web Services Assembly Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort, wsdl (required)
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: wsdlTimeout
For more information on this argument, see "WSDL Management Arguments".
Additional Ant Support:
None
Use the genWsdl
command to generate a WSDL and a JAX-RPC mapping file for assembling Web services bottom up from a Java interface. This command requires either an interfaceName
argument or a className
argument that points to an annotated Java class to provide the WSDL with a value for the service endpoint interface.
The following example illustrates the genWsdl
command. The interfaceName
argument specifies the oracle.j2ee.demo.HelloIntf
interface.
java -jar wsa.jar genWSDL -interfaceName oracle.j2ee.demo.HelloIntf -output wsdl -classpath classes
Generating WSDLs with WSIF Bindings
The genWsdl
command can use the following arguments to add WSIF bindings to the generated WSDL.
the wsifJavaBinding
argument adds WSIF bindings to the WSDL when you are exposing a Java class as a Web service. You must also specify the Java class with the className
argument.
the wsifEjbBinding
argument adds WSIF bindings to the WSDL when you are exposing an EJB as a Web service. You must specify the EJB's home interface in the className
argument and its JNDI name in the jndiName
argument.
the wsifDbBinding
argument adds WSIF bindings to the WSDL when you are exposing a database resource as a Web service. You must specify the className
of the resource's Oracle JPublisher-generated Java class and a database connection.
You can also use the genWsdl
command to add WSIF bindings for multiple ports in the WSDL.
See Also: "Using Web Services Invocation Framework" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on WSIF. |
Generating WSDLs for use with J2SE 5.0 Annotations
If you are generating a WSDL from J2SE 5.0 Annotations, then use the className
argument instead of the interfaceName
argument. The className
argument must identify the implementation class and the @WebService
annotation must be present on the class declaration.
Use the interfaceName
argument if the specified className
does not contain any J2SE 5.0 Annotations.
J2SE 5.0 Annotations require a class name because annotations can appear in either the interface or the implementation class. If the annotations appear only in the interface, WebServicesAssembler can obtain them through its referenced implementation class. If the implementation class also contains annotations, WebServicesAssembler will process them.
In the following example, the genWsdl
command is used to generate a WSDL for use with J2SE 5.0 annotations. The className
argument specifies the oracle.j2ee.demo.HelloImpl
class.
java -jar wsa.jar genWsdl -className oracle.j2ee.demo.HelloImpl -output wsdl -classpath classes
If you want WebServicesAssembler to process only the J2SE 5.0 annotations in the interface, then enter the @WebService
annotation with the serviceEndpointInterface
property in the implementation class file. J2SE 5.0 Annotations will expect all remaining annotations to appear in the service endpoint interface class. For example, if you enter the following annotation in the implementation class file, then WebServicesAssembler will process only the annotations in the demo.myInterface
interface.
@WebService(serviceEndpointInterface="demo.myInterface")
The following command line and Ant task output a JAX-RPC mapping file and a WSDL that corresponds to the Java interface specified by interfaceName
. The results are stored in the etc
directory.
Command Line Example:
java -jar wsa.jar -genWsdl -classpath myservice.jar -output etc -interfaceName com.mycompany.myservice.Hello
Ant Task Example:
<oracle:genWsdl output="etc" > <oracle:porttype interfaceName="com.mycompany.myservice.Hello"/> <oracle:classpath> <pathelement path="myservice.jar" /> </oracle:classpath> </oracle:genWsdl>
Required Arguments:
To use the genWsdl
command, you must specify the following arguments.
General Assembly Arguments: classpath; when generating a WSDL using J2SE 5.0 Annotations, genWsdl
requires either interfaceName or a className that points to an annotated Java class
All Arguments:
The following list identifies all of the arguments that can be used with the genWsdl
command.
Database Assembly Arguments: dataSource, dbConnection, dbUser, wsifDbBinding, wsifDbPort
For more information on these arguments, see "Database Assembly Arguments".
Deployment Descriptor Arguments: ddFileName
For more information on this argument, see "Deployment Descriptor Arguments".
General Assembly Arguments: bindingName, className (required for J2SE 5.0 Annotations), classpath (required), debug, emptySoapAction, help, initialContextFactory, interfaceName (required for J2SE 5.0 Annotations), jndiName, jndiProviderURL, mappingFileName, output, portName, portTypeName, schema, serviceName, strictJaxrpcValidation
For more information on these arguments see, "General Web Services Assembly Arguments".
Java Generation Arguments: valueTypeClassName, wsifEjbBinding, wsifJavaBinding
For more information on these arguments, see "Java Generation Arguments".
JMS Arguments: sendConnectionFactoryLocation, sendQueueLocation
For more information on these arguments, see "JMS Assembly Arguments".
Message Format Arguments: style, use
For more information on these arguments, see "Message Format Arguments".
WSDL Management Arguments: createOneWayOperations, genQos, qualifiedElementForm, soapVersion, targetNamespace, typeNamespace
For more information on these arguments, see "WSDL Management Arguments".
Additional Ant Support:
<port>
tags. In the <port>
tag, genWsdl
can use these arguments: bindingName, name
(same as portName
), portName, sendConnectionFactoryLocation, sendQueueLocation, soapVersion, and uri. For more information, see "How to Configure a Port in an Ant Task".
<porttype>
tags. For more information, see "How to Configure a Port Type in an Ant Task".
tags to specify WSIF bindings for multiple ports. For more information, see "Configuring a WSIF Endpoint for Multiple Java Ports", "Configuring a WSIF Endpoint for Multiple EJB Ports", and "Configuring a WSIF Endpoint for Multiple Database Resource Ports", in the Oracle Application Server Advanced Web Services Developer's Guide.
The following commands generate code to create a Java interface, a proxy/stub, or JAX-RPC value type classes.
genInterface—Generates a Java interface from a WSDL file
genProxy—Generates a proxy/stub from a WSDL file
genValueTypes—Generates JAX-RPC value type classes from an XML schema
For top down Web service development, this command creates a service endpoint interface for each port type and a Java value type class (beans) for any complex type defined in a WSDL. It also creates a JAX-RPC mapping file that describes the mapping between the XML schema types and the Java value type classes. These files can then be used to construct a J2EE Web service client or to create an implementation that can run on the server.
If you are assembling a J2EE Web service client and want to pass in an Oracle specific client configuration, then use the ddFileName
argument.
In addition to a JAX-RPC mapping file, the genInterface
command generates the files listed in Table 18-1 from a WSDL document. The list and descriptions assume that no JAX-RPC mapping file was used to change the default naming conventions of these files. Also note that if there is any conflict between the names of generated Java classes, then they will be resolved according to JAX-RPC rules as described in section 4.3.12, "Name Collisions" in the JAX-RPC specification. For more information, see "Resolving Name Collisions".
Note: Changing any of these generated files is not recommended because they may be overwritten if a WebServicesAssembler command is invoked again. WebServicesAssembler will not overwrite the files generated with thegenInterface command for the schema types under these conditions:
|
Table 18-1 genInterface Generated Files
File Name | Description |
---|---|
<derived_name>.java |
One file is generated for each type defined in the schemas in the specified WSDL. The name of the Java class file, derived_name, is derived from the name of the complex type or element in the schema. The JAX-RPC specification sections 4.2.3, "XML Struct and Complex Type", 4.3.6, "WSDL Fault", and 6.5, "SOAP Fault", describe this class. |
<portTypeName>.java |
The service endpoint interface file. This file contains a Java method for every WSDL operation in the port type. The portTypeName is the value of the |
Note: ThegenInterface command cannot process a WSDL file correctly if it uses multibyte characters in element names. The command will produce class files but they will not compile correctly.
To work around this limitation, set the |
See Also:
|
The following command line and Ant task examples create a service endpoint interface in the src
directory (src/oracle/demo/service
).
Command Line Example:
java -jar wsa.jar -genInterface -output src -wsdl myservice.wsdl -packageName oracle.demo.service
Ant Task Example:
<oracle:genInterface output="src" wsdl="myservice.wsdl" packageName="oracle.demo.service" />
Required Arguments:
To use the genInterface
command, you must specify the following argument.
WSDL Access Arguments: wsdl
All Arguments
The following list identifies all of the arguments that can be used with the genInterface
command.
Deployment Descriptor Arguments: ddFileName
For more information on this argument, see "Deployment Descriptor Arguments".
General Assembly Arguments: classpath, debug, help, mappingFileName, packageName, output, searchSchema, serviceName
For more information on these arguments see, "General Web Services Assembly Arguments".
Java Generation Arguments: dataBinding, mapHeadersToParameters, overwriteBeans, unwrapParameters, valueTypePackagePrefix
For more information on these arguments see, "Java Generation Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort, wsdl (required)
For more information on these arguments see, "WSDL Access Arguments".
WSDL Management Arguments: wsdlTimeout
For more information on this argument see, "WSDL Management Arguments".
Additional Ant Support:
None
Use the genProxy
command to create a static proxy stub that can be used by a J2SE Web service client. This command creates all of the Java files required to contact the ports specified in the WSDL. If you have an Oracle specific client configuration, use the ddFileName
argument to pass it to the command.
You must compile the proxy code before you can use it.
The genProxy
command generates the files Table 18-2 from a WSDL document. The list and descriptions assume that no JAX-RPC mapping file was used to change the default naming conventions of these files. Also note that if there is any conflict between the names of generated Java classes, then they will be resolved according to JAX-RPC rules as described in section 4.3.12, "Name Collisions" in the JAX-RPC specification. For more information, see "Resolving Name Collisions".
Note that changing any of these generated files is not recommended because they may be overwritten if the WebServicesAssembler command is invoked again.
Note: WebServicesAssembler will not overwrite the files generated with thegenProxy command for the schema types under these conditions:
|
Table 18-2 genProxy Generated Files
File Name | Description |
---|---|
<derived_name>.java |
One file is generated for each type defined in the schemas in the specified WSDL. The name of the Java class file, derived_name, is derived from the name of the complex type or element in the schema. The JAX-RPC specification sections 4.2.3, "XML Struct and Complex Type", 4.3.6, "WSDL Fault", and 6.5, "SOAP Fault", describe this class. |
<portName>Client.java |
A utility class file is generated for each port in the WSDL. This file contains code that shows you how to call your service. You should use this file only to test your service; not as the vehicle in which your clients call the service. It is example code. The portName is the value of the Note: this file is not mandated by the JAX-RPC specification. |
<portTypeName>.java |
The service endpoint interface file. This file contains a Java method for every WSDL operation in the port type. The portTypeName is the value of the |
<serviceName>.java |
A service interface file with this name is generated for every service in the WSDL document. The serviceName is the value of the |
Runtime directory/package |
These directories contain the files used internally by the Web services proxy code. You should not use any of these files directly because they may change or be removed in a future release. |
See Also:
|
The following command line and Ant task examples create all of the proxy code and store it in the proxysrc
directory.
Command Line Example:
java -jar wsa.jar -genProxy -output proxysrc -wsdl myservice.wsdl
Ant Task Example:
<oracle:genProxy output="proxysrc" wsdl="myservice.wsdl" />
Required Arguments:
To use the genProxy
command, you must specify the following argument.
WSDL Access Arguments: wsdl
All Arguments:
The following list identifies all of the arguments that can be used with the genProxy
command.
Deployment Descriptor Arguments: ddFileName
For more information on this argument, see "Deployment Descriptor Arguments".
General Assembly Arguments: classpath, debug, help, mappingFileName, packageName, output, searchSchema, serviceName, useDimeEncoding
For more information on these arguments see, "General Web Services Assembly Arguments".
Java Generation Arguments: dataBinding, mapHeadersToParameters, overwriteBeans, unwrapParameters, valueTypePackagePrefix
For more information on these arguments see, "Java Generation Arguments".
JMS Assembly Arguments: replyToConnectionFactoryLocation, replyToQueueLocation
For more information on these arguments see, "JMS Assembly Arguments".
Message Format Arguments: mtomSupport
For more information on this argument, see "Message Format Arguments".
Proxy Arguments: endpointAddress, genJUnitTest
For more information on these arguments see, "Proxy Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort, wsdl (required)
For more information on these arguments, see "WSDL Access Arguments".
WSDL Management Arguments: wsdlTimeout
For more information on this argument see, "WSDL Management Arguments".
Additional Ant Support:
<handler>
tags—For more information, see "How to Configure Handlers in an Ant Task".
<port>
tags—In the <port>
tag, genProxy
can use these arguments: endpointAddress, name
(same as portName
), portName, replyToConnectionFactoryLocation, and replyToQueueLocation. For more information, see "How to Configure a Port in an Ant Task".
Use the genValueTypes
command to create JAX-RPC value type classes (beans) from the specified schemas. This command creates the beans for schema-driven Web service development.
WebServicesAssembler can create more than one value type class for each genValueTypes
invocation. The command supports more than one schema
argument on the command line or <schema value="">
line in an Ant task.
In addition to the beans, this command creates the custom-type-mappings.xml
and jaxrpc-mappings.xml
files. The custom-type-mappings.xm
l
file makes it easier to configure the custom serializer. The generated custom type mapping file conforms to the service side schema, but it can be modified slightly to be used on the client side.
The jaxrpc-mappings.xml
file is a partial JAX-RPC mapping file that can be supplied when generating the WSDL for bottom up Web service development.
See Also:
|
The following command line and Ant task examples create a value type (bean) for every complex type defined in the schemas mySchema.xsd
and otherSchema.xsd
and creates the files custom-type-mappings.xml
and jaxrpc-mappings.xml
. The beans and files are stored in the build
directory.
Command Line Example:
java -jar wsa.jar -genValueTypes -schema mySchema.xsd -schema otherSchema.xsd -packageName com.mycompany -output build
Ant Task Example:
<oracle:genValueTypes packageName="com.mycompany" output="build"> <oracle:schema value="otherSchema.xsd"/> <oracle:schema value="mySchema.xsd"/> </oracle:genValueTypes>
Required Arguments:
To use the genValueTypes
command, you must specify the following argument.
General Assembly Arguments: schema
All Arguments:
The following list identifies all of the arguments that can be used with the genValueTypes
command.
General Assembly Arguments: debug, help, packageName, output, schema (required)
For more information on these arguments see, "General Web Services Assembly Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort
For more information on these arguments see, "WSDL Access Arguments".
Additional Ant Support:
None
The following commands create deployment descriptors or files that are used in generating descriptors for the EAR.
genApplicationDescriptor—Creates an application.xml
file
genDDs—Creates deployment descriptors
Use the genApplicationDescriptor
command to create an application.xml
file that can be used when generating an EAR.
The input
argument must be a directory that contains the WARs and EJB JARs that will be placed in the EAR. The generated application.xml
will contain tags for each of the WARs and EJB JARs found in the specified input
directory.
Command Line Example:
java -jar wsa.jar -genApplicationDescriptor -input src/ejb -output build
Ant Task Example:
<oracle:genApplicationDescriptor input="src/ejb" output="build" />
Required Arguments:
To use the genApplicationDescriptor
command, you must specify the following argument.
General Assembly Arguments: input
All Arguments:
The following list identifies all of the arguments that can be used with the genApplicationDescriptor
command.
Deployment Descriptor Arguments: context
For more information on this argument, see "Deployment Descriptor Arguments".
General Assembly Arguments: debug, help, input (required), output
For more information on these arguments see, "General Web Services Assembly Arguments".
Additional Ant Support:
None
Use the genDDs
command in top down or bottom up Web service generation to create the web.xml
, webservices.xml
, and oracle-webservices.xml
deployment descriptors.
The following command line and Ant task examples create the deployment descriptors and store them in the WEB-INF
directory.
Command Line Example:
java -jar wsa.jar -genDDs -output WEB-INF -wsdl myservice.wsdl -classpath myservice.jar -interfaceName com.mycompany.myservice.Hello -className com.mycompany.myservice.HelloImpl
Ant Task Example:
<oracle:genDDs output="WEB-INF" wsdl="myservice.wsdl" classpath="myservice.jar" > <oracle:porttype interfaceName="com.mycompany.myservice.Hello" className="com.mycompany.myservice.HelloImpl"/> </oracle:genDDs>
Required Arguments
To use the genDDs
command, you must specify the following arguments.
General Assembly Arguments: className, interfaceName
WSDL Access Arguments: wsdl
All Arguments:
The following list identifies all of the arguments that can be used with the genDDs
command.
Deployment Descriptor Arguments: appendToExistingDDs, context, ddFileName, uri
For more information on these arguments, see "Deployment Descriptor Arguments".
General Assembly Arguments: className (required), classpath, debug, ejbName, help, interfaceName (required), mappingFileName, output, serviceName, strictJaxrpcValidation, useDimeEncoding
For more information on these arguments see, "General Web Services Assembly Arguments".
JMS Assembly Arguments: sendConnectionFactoryLocation, sendQueueLocation
For more information on these arguments see, "JMS Assembly Arguments".
WSDL Access Arguments: httpNonProxyHosts, httpProxyHost, httpProxyPort, wsdl (required)
For more information on these arguments see, "WSDL Access Arguments".
WSDL Management Arguments: wsdlTimeout
For more information on this argument see, "WSDL Management Arguments".
Additional Ant Support:
<port>
tags. In the <port>
tag, genDDs
can use these arguments: name
(same as portName
), portName, sendConnectionFactoryLocation, sendQueueLocation, and uri. For more information, see "How to Configure a Port in an Ant Task".
<porttype>
tags. For more information, see "How to Configure a Port Type in an Ant Task".
<handler>
tags. For more information, see "How to Configure Handlers in an Ant Task".
The following commands return a short description of WebServicesAssembler commands and the version number of the tool.
Use the help
command to return a list of WebServicesAssembler commands and a brief description. WebServicesAssembler will also return help when it is run:
without any commands or arguments. For example,
java -jar wsa.jar
with incorrect commands or arguments. For example,
java -jar wsa.jar -myProxy -ootput proxysrc -wsdl myservice.wsdl
You can get help on a specific command by running WebServicesAssembler with the command followed by -help
. For example, the following command returns detailed help on the genProxy
command and its required and optional arguments.
java -jar wsa.jar -genProxy -help
The help
command is supported only on the command line. There is no comparable Ant task. The following command line example returns help text on the commands and arguments supported by WebServicesAssembler.
Command Line Example:
java -jar wsa.jar -help
Ant Task Example:
No Ant support provided.
Required Arguments:
None
All Arguments:
The following argument can be used with the help
command:
General Assembly Arguments: debug
For more information on this argument see, "General Web Services Assembly Arguments".
Additional Ant Support:
None
Use the version
command to obtain the version number of the WebServicesAssembler tool.
Command Line Example:
java -jar wsa.jar -version
Ant Task Example:
No Ant support provided.
Required Arguments:
None
All Arguments:
General Assembly Arguments: debug, help
For more information on these arguments see, "General Web Services Assembly Arguments".
Additional Ant Support:
None
This section describes the arguments that can be called for WebServicesAssembler commands.
This section describes common arguments that can be used by many of the WebServicesAssembler commands. They include file-related input and output arguments, WSDL-related arguments, and mapping-related arguments.
appName <String>
Specifies the name of an application. Usually, this name is used as a base value for other arguments like context
and uri
. The value of this argument is also used to name the EAR and the WAR files if the ear
and war
arguments are not specified.
classFileName <String>
Identifies the Java file name of the implementation class specified in the className
argument. If necessary, this file will be compiled during an assembly.
className <String>
Specifies the name of the class (including the package name) that is the implementation class for the Web service.
Using this argument adds the <servlet-class>
element to web.xml
.
If you are exposing an EJB as a Web service, the value of the className
argument must be the EJB's home interface.
If this argument is used with the wsifJavaPort
argument, a classname
attribute is added to the java:address
element in the port
component of the WSDL.
If this argument is used with the wsifEjbPort
argument, a classname
attribute is added to the ejb:address
element in the port
component of the WSDL.
classpath <String>
Specifies the classpath that contains any user-created classes given to WebServicesAssembler. One reason to specify this argument is if you have already created some value type classes or exceptions and you do not want WebServicesAssembler to overwrite them.For commands that generate a WAR file, such as the *Assemble
commands, this argument enables you to point to classes the Web service has a dependency on and that should not be placed in the generated WAR.This argument does not cause any additional classes to be copied to a generated WAR file. Any classes needed at runtime or deployment time must either be copied to the WAR or EAR manually or made available on the application server classpath using server configuration options.
To include classes in the WAR file, you also have the option of using the input
argument.
If you list multiple paths on the classpath, separate them with a colon (:) if you are using the UNIX operating system. If you are using the Windows operating system, separate multiple paths with a semicolon (;).
debug <true|false>
Indicates whether all detailed diagnostic messages should be printed for a given command. Default value is false
.
The following command line and Ant task examples will display diagnostic messages on the performance of the assemble
command.
Command Line Example:
java -jar -wsa.jar -assemble -debug true...
Ant Task Example:
<oracle:assemble debug="true" .... />
ear <file name>
Specifies the name and location of the generated EAR. The following example creates the EAR file myService.ear
in the dist
directory.
-ear dist/myService.ear
The following list describes how WebServicesAssembler interprets the value of the ear
argument.
If the value of the ear
argument ends with a file name with the extension ".ear
" (as in the preceding example), then an EAR file with the specified name is created at the location specified by the ear
argument. The output
argument is not used to determine the location of the EAR file.
In all other cases, the name is assumed to be a directory name. An EAR file is not created. Instead, the contents of the EAR will be written to the indicated directory.
If you specify a value for the output
argument and do not provide the ear
argument, then the EAR file will be given the value of the appName
argument as its default name. For example, if the value of output
is build
and the value of appName
is myService
, and ear
is not specified, then the EAR file will be created as build
/myService.ear
.
Note: If you specify the same directory for theear and the output argument, then WebServicesAssembler will return an error. |
The ear
and war
arguments can be used together in the same command line or Ant task. Table 18-3 describes the behavior of these arguments based on whether they specify a file or a directory.
Table 18-3 Behavior of ear and war Arguments for File and Directory Values
ear and war Argument Combination | Behavior |
---|---|
|
If the
|
|
If the
|
|
If the
|
|
If the
|
|
If neither the
In these examples, application_name represents the value of the |
ejbName <String>
The name of the EJB to be exposed as a Web service. Note that this is not a class name; it is the unique name of the EJB that is specified in the <ejb-name>
tag in the ejb-jar.xml
file.
If the EJB is version 2.1, using this argument adds the <ejb-link>
element to webservices.xml
.
emptySoapAction <true|false>
If true
, the value of the soapAction
attribute for each SOAP binding operation in the generated WSDL will be set to an empty string. If false
(default), the target namespace and the operation name (<
target-namespace
>/<
operation-name
>
) is used as the value of the soapAction
attribute.
Tools from other vendors that use OracleAS Web Services WSDLs to generate the client-side proxy may not be able to recognize or honor the default soapAction
value. Setting this argument to true
increases the chances of interoperability with these tools.
help
Displays a help message for a given command. The help
argument can either precede or follow the command.
The following command line and Ant task examples will display a help message on the assemble
command.
Command Line Example:
java -jar -wsa.jar -assemble -help ...
or
java -jar -wsa.jar -help -assemble ...
Ant Task Example:
<oracle:assemble debug="help" .... />
initialContextFactory <String>
Specifies the name of the factory that will provide the initial context. This is an optional argument that can be called by the genWsdl
or ejbAssemble
command when configuring an EJB WSIF port with wsifEjbBinding
or wsifEjbPort
. If you do not provide a value for this attribute, the value in the jndi.properties
file will be used.
input <String>
Specifies the directory or JAR containing the classes that should be copied to WEB-INF/classes
. This argument will be added to the classpath used by the WebServicesAssembler. The ejbAssemble
command assumes the value of the input is an EJB JAR file or a directory that contains the contents of an EJB JAR.
If this argument specifies a JAR, then it will be expanded and its contents copied to the WEB-INF/classes
directory.
The input
argument can be used more than once on the command line or in an Ant task. In an Ant task, write the multiple occurrences in separate tags and include the value
attribute. Example 18-1 illustrates multiple instances of input
in an Ant task.
Example 18-1 Multiple Instances of input in an Ant Task
<oracle:jmsAssemble linkReceiveWithReplyTo="true" targetNamespace="http://oracle.j2ee.ws/jms-doc" typeNamespace="http://oracle.j2ee.ws/jms-doc/types" serviceName="JmsService" appName="jms_service" context="jms_service" input="./demo/build/mdb_service.jar" output="./demo/dist" input="first.jar" > <oracle:input value="second.jar"/> <oracle:input value="third.jar"/> </oracle:jmsAssemble>
interfaceFileName <String>
Specifies the path and name of the service endpoint interface (SEI) Java source code file. If the specified file name cannot be found, WebServicesAssembler will stop processing.
The presence of the interfaceFileName
argument can play a role in how WebServicesAssembler represents the parameter names of Java methods in the generated WSDL.
See Also: "How to Represent Java Method Parameter Names in the WSDL" for more information on this topic. |
interfaceName <String>
Specifies the name of a Java class (including the package name) that contains the service endpoint interface (SEI).
Using this argument adds a <service-endpoint-interface>
String
</service-endpoint-interface>
element to WEB-INF/webservices.xml
, where String
is the value provided for interfaceName
.
Using this argument with any of the commands which assemble a Web service from database resources (plsqlAssemble
, sqlAssemble
, dbJavaAssemble
, or aqAssemble
), adds the <service-endpoint-interface>
String
</service-endpoint-interface>
element to the serviceName
-java-wsdl-mapping.xml
file, where String
is the value provided for interfaceName
and serviceName
is the value of the serviceName
argument.
jndiProviderURL <String>
Specifies the URL for the JNDI Provider. This is an optional argument that can be called by the genWsdl
or ejbAssemble
command when configuring an EJB WSIF port with wsifEjbBinding
or wsifEjbPort
. If you do not provide a value for this attribute, the value in the jndi.properties
file will be used.
mappingFileName <String>
Specifies a file location that points to a JAX-RPC mapping file. If the specified file name cannot be found, WebServicesAssembler will stop processing.
Using this argument adds the <jaxrpc-mapping-file>
element to webservices.xml
. Note that the location and name of the file may be changed when it is written to the deployment descriptor. The contents of the file may be modified before being placed in the archive if some mappings were not defined in the original file.
See Also: "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on the contents of the JAX-RPC mapping file and how it is used. |
output <String>
Specifies the directory where generated files will be stored. If the directory does not exist, it will be created. If you do not specify the output
argument, then the output will be stored in the current directory.
Except when used with the genConcreteWsdl
command, the target of the output
argument is always assumed to be a directory. In the case of the genConcreteWsdl
command, the target is assumed to be a file.
The output
argument is typically used with the ear
and war
arguments.
Note: If you specify the same directory for theoutput and the ear (or war ) argument, then WebServicesAssembler will return an error. |
packageName <String>
Specifies the package name that will be used for generated classes if no package name is declared in the JAX-RPC mapping file. If packageName
is not specified and not declared in the mapping file, then the package name will be derived from the target namespace of the WSDL.
See Also: "Default Algorithms to Map Between Target WSDL Namespaces and Java Package Names" for more information on namespace to package mappings. |
Note: ThepackageName argument affects only the package name for the service endpoint interface and any schema types that have the same target namespace as the WSDL. If there are schema value types in a different namespace, then WebServicesAssembler generates them into a different package by default. For information on generating the code into a single package, see "Generating Code into a Single Package from a WSDL with Multiple Namespaces" in the Oracle Application Server Advanced Web Services Developer's Guide. |
portName <String>
Specifies the name of a port in a WSDL document. This argument populates the <port name="...">
WSDL element.
If a port name is not specified, then the default will be based on either the transport and SOAP version, or on the WSIF type. The default port name will be one of the following values.
HttpSoap11
HttpSoap12
JmsSoap11
JmsSoap12
WsifEjb
WsifJava
portTypeName <String>
Specifies the name of the port type to use in the generated WSDL. This argument populates the <portType name="...">
WSDL element.
restSupport <true|false>
Specifies whether REST (Representational State Transfer) support will be enabled for this Web service. The default value is false
.
REST services allow you to get and modify service objects with the HTTP GET and POST commands. Another feature of REST Web services is the use of XML documents, not SOAP envelopes, for sending messages.
See Also: Chapter 12, "Assembling REST Web Services" for more information on implementing Web services with REST support. |
schema <String>
Specifies the relative path or URL to an XML schema document. This argument enables you to specify a schema for value types instead of letting WebServicesAssembler generate them. This argument must be used in conjunction with a JAX-RPC mapping file.
The schema
argument can be used more than once on the command line or in an Ant task. In an Ant task, write the multiple occurrences in separate tags and include the value
attribute. Example 18-2 illustrates multiple instances of schema
in an Ant task.
searchSchema <true|false>
Indicates whether all of the types in the schemas listed in the WSDL should be processed. When this argument is set to true
(default), all of the types will be processed. This is useful when using a Web service implementation that uses types found in the schemas, but are not directly referenced by the WSDL. When this argument is set to false
, the types that are not referenced by the WSDL will not be processed.
serviceName <String>
Specifies the service name. The serviceName
argument is used to identify the generated or packaged WSDL file (serviceName.wsdl
) and the mapping file (serviceName-java-wsdl-mapping.xml
). In bottom up Web service assembly, this argument also provides a value for the <service name="...">
WSDL element.
When this argument is used in top down Web service and proxy assembly, the WSDL will expect to find a service with this name. In this case, the value of the <service name="...">
WSDL element will not be changed.
strictJaxrpcValidation <true|false>
Determines whether the service endpoint interface, exceptions, and value types will be validated according to all of the JAX-RPC validation rules. If this argument is not specified or set to true
(default), the following validation checks are performed:
the service endpoint interface implements java.rmi.Remote
all methods throw java.rmi.RemoteException
all value types and properties in exceptions follow JAX-RPC rules
If any of these validation checks fail, then processing stops and an error is thrown describing what is wrong with the interface.
If this argument is set to false
, then a service endpoint interface does not have to implement java.rmi.Remote
and methods do not have to throw java.rmi.RemoteException
. However, if any method has parameters or exceptions that do not follow JAX-RPC rules, then the method will be ignored and will not be processed.
In the case of Beans and exceptions, if this argument is set to false, any invalid property in the Bean (or exception) will be ignored. Valid properties will be processed and included in the WSDL. Note that this behavior might produce a wire-level format that the user is not expecting. For invalid properties, WebServicesAssembler will throw a warning.
useDimeEncoding <true|false>
Specifies whether DIME encoding will be used for streaming SOAP messages with attachments over the wire. If useDimeEncoding
is set to true
, DIME encoding is used for attachments instead of MIME. The default value is false
.
Using this argument adds the <use-dime-encoding>
element to oracle-webservices.xml
.
Note: The messages generated with theuseDimeEncoding argument are not interoperable and are incompatible with non-Oracle Web services or earlier versions of Oracle Application Server. Generating a Web service with this argument is useful for in-house projects where performance is key. |
See Also: "Working with DIME Attachments" in the Oracle Application Server Advanced Web Services Developer's Guide provides more information about working with DIME encoding and attachments. |
war <file name or directory name>
Specifies the name of the WAR to generate. If a file is specified, it must have the .war
extension. If a directory is specified, the contents of the WAR will be written to the indicated directory. The following example creates the WAR file myService.war
in the dist
directory.
-war dist/myService.war
The following list describes how WebServicesAssembler interprets the value of the war
argument.
If the value of the war
argument ends with a file name with the extension ".war
" (see the preceding example), then a WAR file with the specified name is created at the location specified by the war
argument. The output
argument is not used to determine the location of the WAR file.
In all other cases, the value is assumed to be a directory name. The WAR file will be written to the indicated directory.
If you specify a value for the output
argument and do not provide the war
argument, then the WAR will be placed inside of an EAR. The name of the WAR file inside of the EAR will be appName
.war
.
Note: If you specify the same directory for thewar and the output argument, then WebServicesAssembler will return an error. |
See Also:
|
These arguments can be used to control the behavior of session state.
callScope <true|false>
Indicates that the servant is to be created for each call and is garbage-collected after each call. Default value is false
. An error will be thrown if both callScope
and session
are set to true
.
Using this argument with the value set to true
adds the <param name="scope">call</param>
element to oracle-webservices.xml
.
recoverable <true|false>
Indicates whether applications with session state are recoverable. This argument can be used only when the service is exposed as a stateful Web service with session scope. The default, true
, causes session state to be preserved. If it is recoverable, then a boolean <distributable>
element is added to web.xml
. Recoverable means that you want the service to be able to recover in a distributed environment if the node that you are interacting with goes down. This means that the Web service state must be also be distributable.
If recoverable
is false
, then the <distributable>
element will not be added to web.xml
.
session <true|false>
Indicates that the servant instance is to be preserved for the duration of the HTTP session. This argument is valid only for HTTP transport. Session timeout can be tuned by the timeout
argument. Default value is false
. If timeout
is set, then session
is set to true
by default. An error will be thrown if both callScope
and session
are set to true
.
Using this argument adds the <param name="scope">session</param>
element to oracle-webservices.xml
.
timeout <int>
Specifies the number of seconds a session should last before it times out. The default value is 60 seconds. If the value is 0 or a negative number, then the session will not time out.
If a value is set for this argument, then the session
argument is automatically set to true
. If the session
argument is true
and timeout
is not set, then the session will time out after 60 seconds.
Using this argument adds the <param name="session-timeout">
value
</param>
element to oracle-webservices.xml
, where value
is the integer value given to timeout
.
The following arguments can be used by the corbaAssemble
command. They can be used to control how a Web service is assembled using CORBA servant objects.
corbanameURL <String>
Specifies a URL for locating the CORBA object using a CORBA Naming Service.
idlInterfaceName <String>
Specifies the name of the interface in the idl
from which the Web service will be generated.
idljPath <String>
Specifies the path to the directory containing the IDL-to-Java compiler (idlj
) if it is not already specified in the path
.
These arguments are used by the commands that assemble a Web service from database artifacts such as PL/SQL stored procedures, SQL statements, Oracle Advanced Queues (AQ), and Java classes inside the Java VM in an Oracle database.
See Also: Chapter 10, "Assembling Database Web Services" for more information on assembling Web services from database artifacts. |
aqConnectionFactory <String>
Specifies the JNDI location of the Oracle Streams AQ JMS queue connection factory for the exposed AQ.
aqConnectionLocation <String>
Specifies the JDNI location of the Oracle Streams AQ JMS queue connection connecting to the exposed AQ.
dataSource <String>
Specifies the JNDI location of the data source used by the Web services at runtime.
Using this argument adds the following param
name
attribute to the <implementor>
element in oracle-webservices.xml
. The dataSource
value
variable is the path specified with the dataSource
argument.
<param name="databaseJndiName">
dataSource value
</param>
For example, if you specify dataSource="ws/dbws/src/query/datasource"
in an Ant task, the <implementor>
element will be written as follows.
<implementor type="database"> <param name="databaseJndiName">ws/dbws/src/query/datasource</param></implementor>
dbConnection <String>
Specifies the JDBC URL for the database. This argument is used with the dbUser
argument to connect to a database at code-generation time.
dbJavaClassname <String>
Specifies the name of the server-side Java class to be published as a Web service.
dbUser <String>
Specifies the database schema and password in the form of user/
password. This argument is used with the dbConnection
argument to connect to a database at code-generation time.
If you attempt to access the database by invoking WebServicesAssembler on the command line and do not specify a password with -dbUser
, you will be prompted for a password. This is to protect the password being shown in clear text.
jpubProp <String>
Specifies the name of a file with properties to control the Oracle JPublisher translation process.
See Also:
|
sql <String>
The value of the sql
argument has a different meaning depending on whether it is used with aqAssemble
or plsqlAssemble
.
aqAssemble
—When used with aqAssemble
, the value of sql
is an AQ queue name.
plsqlAssemble
—When used with plsqlAssemble
, the value of sql
is a PL/SQL package name.
The sql
argument can handle case-sensitive names in SQL statements. For example, the use of quotes in the following SQL statement indicates that the package name, SIMple
, is case sensitive.
create package "SIMple" as procedure foo; end;
To use the SIMple
package name as the target of the sql
argument on the command line, enter:
-sql '"SIMple"'
To use it in an Ant task, enter:
sql=""SIMple""
Note that in each case, the quotations enclosing SIMple
are required. The quotations and the package name are passed to Oracle JPublisher. Oracle JPublisher uses the quotations to resolve the identifier against the name in the database.
sqlstatement <String>
Specifies the DML statement or SQL query to be published as a Web service.
SQL statements must be either queries or DML statements.
SQL statements are tagged with the name that will be used in the WSDL and in generated Java code.
methodName
=<statement
>
The methodName
indicates the operation name for the SQL statement in the generated Web services.
SQL statements may contain embedded host variables with a parameter name and corresponding SQL type. The parameter name is used in the WSDL and in the generated Web service operations. The parameter is given in the following form.
:{
param_name
param_sql_type
}
In this example, param_name
defines the identifier for the parameter in the generated Web service, and param_sql_type
defines the SQL type name for that parameter.
The sqlstatement
argument cannot be used to specify stored procedures.
When you pass a SQL statement on the WebServicesAssembler Ant task, you must ensure that it is correctly quoted. The value of sqlstatement
can be quoted using standard XML quotations as shown in Table 18-4:
Table 18-4 Valid Quoting Symbols for the sqlstatement Ant Task
Symbol | Quotation |
---|---|
& |
& |
" |
" |
< |
< |
> |
> |
' |
' |
Multiple sqlstatement
arguments can be specified on the command line or Ant task. In an Ant task, write the multiple occurrences in separate tags and use the value
attribute. Example 18-3 illustrates multiple instances of the sqlstatement
argument in an Ant task.
Example 18-3 Multiple Instances of sqlstatement in an Ant Task
<oracle:sqlAssemble dbUser="scott/tiger" dbConnection="jdbc:oracle:thin:@dsunrde22:1521:sqlj" dataSource="jdbc/OracleManagedDS" appName="query"> <sqlstatement value="getEmp=select ename, sal from emp where empno=:{id NUMBER}"/> <sqlstatement value="getEmpBySal=select ename, sal from emp where sal>:{mysal NUMBER}"/> </oracle:sqlAssemble>
sqlTimeout <int>
Specifies timeout, in seconds, for the database operation. Database operations can include PL/SQL stored function or procedure invocations, SQL queries, and DML statements. The default is 0, which means the service never times out.
sysUser <String>
Specifies the name and password of a user with SYS
privileges in the form of dbSysUser/syspassword
. Using this argument allows PL/SQL and Java wrapper code to be installed automatically into the database at code-generation time.
useDataSource <true|false>
The useDataSource
argument can be specified on the command line or in the Ant task only when the wsifDbBinding
or wsifDbPort
argument is also present. If useDataSource
is specified and neither of these arguments are present, then an error is thrown.
The useDataSource
argument determines whether the value of the dataSource
argument will be used in the WSDL port tag. If useDataSource
is not specified, or specified with the value of true
, then the dataSource
value used in the command line or Ant task is used in the WSDL port tag. If useDataSource
is specified with the value of false
, then the dbConnection
value used in the command line or Ant task is used in the WSDL port tag.
wsifDbBinding <true|false>
This argument is used in bottom up Web services assembly to add WSIF SQL bindings to the WSDL. WebServicesAssembler will generate native WSIF SQL bindings in addition to SOAP bindings in the WSDL. This argument's default value is false
.
See Also:
|
wsifDbPort <true|false>
This argument is used in bottom up Web services assembly to add WSIF bindings for database resources for multiple ports to the WSDL. It can be used only in Ant tasks.
See Also: "Configuring a WSIF Endpoint for Multiple Database Resource Ports" in the Oracle Application Server Advanced Web Services Developer's Guide provides more information on how to use |
The following arguments can be used by the jmsAssemble
command to assemble a JMS Endpoint Web service EAR or WAR directory.
See Also:
|
Of the following arguments, replyToConnectionFactoryLocation
, replyToQueueLocation
, sendConnectionFactoryLocation
, and sendQueueLocation
can be used by JMS transport as well as by JMS assembly.
deliveryMode <String>
Specifies the default value of the JMSDeliveryMode
header field. This field contains the delivery mode specified when the message was sent. The values for deliveryMode
supported by the JMS specification are PERSISTENT
and NON_PERSISTENT
.
genJmsPropertyHeader <true|false>
By default, JMS Endpoint Web services always publish the following JMS message properties of SOAP headers defined on the generated WSDL.
message ID
correlation ID
the ReplyTo destination, including its name, type, and factory
The corresponding schema definition of the JMS-specific header and its binding will be included in the WSDL. Set this argument to false
and the OracleJmsProperties
on the wire SOAP message will be ignored at runtime. Default value is true
.
jmsTypeHeader <String>
The value of this argument is used to specify the default value of the JMSType
header field for the JMS messages that are propagated by the send
operation to a JMS destination. For example, a possible value for jmsTypeHeader
could be My Quote Message
. No default value is provided.
linkReceiveWithReply <true|false>
Determines whether the receive
operation will be linked to the reply-to destination. When this argument is true
, either receive destination/connection-factory or reply-to destination/connection-factory must be set. Default value is false
.
payloadBindingClassname <String>
The fully-qualified Java class name of the content object of javax.jms.ObjectMessage
instance if no data binding is used. The content is not a Java value type but an XML fragment. The only valid values are java.lang.String
and javax.xml.soap.SOAPElement
. Default value is java.lang.String
.
priority <int>
Specifies the default integer value of the JMS message priority header field for the JMS messages that are propagated by the send
operation to a JMS destination. Values can range from 0 to 9, with 0 as lowest priority and 9 as highest.
receiveConnectionFactoryLocation <String>
JNDI name of the JMS ConnectionFactory
used for the receive
operation. The type of ConnectionFactory
must be consistent with the receive
destination. No default value is provided.
receiveQueueLocation <String>
JNDI name of the JMS Queue used for the receive
operation. The receiveQueueLocation
and receiveTopicLocation
arguments are mutually exclusive and cannot both be set. No default value is provided.
receiveTimeout <int>
The value of this argument is used to specify the default value for the amount of time that the receive
method is blocked to get a message. The receiveTimeout
value is expressed in seconds. The default value, 0, means that blocking never expires and the call blocks indefinitely.
receiveTopicLocation <String>
JNDI name of the JMS Topic used for the receive
operation. No default value is provided. The receiveQueueLocation
and receiveTopicLocation
arguments are mutually exclusive and cannot both be set.
replyToConnectionFactoryLocation <String>
Specifies the JNDI name of the JMS connection factory to be used as the default reply-to of all send
operation JMS messages. The type of ConnectionFactory
must be consistent with the reply-to destination. No default value is provided. This argument can be used for JMS Web service assembly or for JMS transport.
When this argument is used for JMS transport, it specifies the JNDI name of the JMS ConnectionFactory
to be used as the default reply-to of all Web service operations that send SOAP messages over the wire.
replyToQueueLocation <String>
Specifies the JNDI name of the JMS queue to be used as the default reply-to of all send
operation JMS messages. No default value is provided. The replyToQueueLocation
and replyToTopicLocation
arguments are mutually exclusive and cannot both be set. This argument can be used for JMS Web service assembly or for JMS transport.
When this argument is used for JMS transport, it specifies the JNDI name of the JMS queue to be used as the default reply-to of all Web service operations that send SOAP messages over the wire.
replyToTopicLocation <String>
Specifies the JNDI name of the JMS Topic to be used as the default reply-to of all send
operation JMS messages. No default value is provided. The replyToQueueLocation
and replyToTopicLocation
arguments are mutually exclusive and cannot both be set.
sendConnectionFactoryLocation <String>
Specifies the JNDI name of the JMS ConnectionFactory
used to obtain a connection for the JMS send
operation. The type of ConnectionFactory
must be consistent with the send
destination. No default value is provided. This argument can be used for JMS Web service assembly or for JMS transport.
When this argument is used for JMS transport, it specifies the JNDI name of the JMS ConnectionFactory
used to obtain a connection for the Web service operation that sends the SOAP messages over the wire.
sendQueueLocation <String>
Specifies the JNDI name of the JMS queue to be used for the JMS send
operation. No default value is provided. The sendQueueLocation
and sendTopicLocation
arguments are mutually exclusive and cannot both be set. This argument can be used for JMS Web service assembly or for JMS transport.
When this argument is used for JMS transport, it specifies the JMS queue to be used for the Web service operation that sends the SOAP messages over the wire.
sendTopicLocation <String>
JNDI name of JMS Topic used for send
operation. No default value is provided. The sendQueueLocation
and sendTopicLocation
arguments are mutually exclusive and cannot both be set.
timeToLive <int>
The value of this argument specifies the default time-to-live value of a JMS send
operation. The value of timeToLive
, expressed in seconds, is a relative value—not absolute. When a message is sent, its expiration time is calculated as the sum of the time-to-live value specified on the JMS send
method and the current GMT value. If the argument is not set or if it is set to 0, then the message will never expire.
These arguments can be used to control the contents of the generated proxy code.
endpointAddress <URL>
Specifies the URL of the endpoint address used to contact the Web service. If you use this argument, then the endpoint address in the WSDL is ignored.
genJUnitTest <true|false>
If genJUnitTest
is set to true
, then a JUnit test will be created for each exposed method in the Web service and stored in the same directory as the service endpoint interface. The JUnit test which is created is only a template; you must provide the actual test code for the method. The default value is false
.
The following arguments can be used to control how Web service deployment is performed.
appendToExistingDDs <true|false>
Determines whether entries for a new Web service will be appended to the existing deployment descriptors or whether they will be overwritten. The deployment descriptors that can be affected by this argument are oracle-webservices.xml
, web.xml
, and webservices.xml
.
If the argument is set to true
, any deployment descriptors in the output location will be updated with the entries needed for a new service. If false
, any existing deployment descriptors in the output location will be overwritten. Default value is false
.
See Also: "How to Assign Multiple Web Services to an EAR or WAR Archive" for information on how to use |
context <String>
Specifies the root context for the Web application. You cannot specify an empty string for context
. If you do not provide a value for context
, then its default value is determined as follows:
If the command supports the appName
argument, then the default value for context
is the value of the appName
argument. If the command does not support the appName
argument, then the default value is the name of the first service in the WSDL.
If the command does not use a WSDL, for example genApplicationDescriptor
, then the default value for context
is the name of the WAR file without the -web.war
or .war
extension.
For version 2.1 EJBs, the value of context
is placed in the <context-root>
element in the oracle-webservices.xml
deployment descriptor file.
For Web applications, the value of context
is placed in the <context-root>
element in the application.xml
deployment descriptor file.
The URL is built from the protocol, the host and the port. For example,
http://localhost:8888/
host
/
port
The protocol, http://localhost:8888/
is set at deployment time and is used to contact the Web service. The second part, the host
is provided by the context
argument. The third part, the port
, is provided by the uri
argument. The full URL is created by concatenating the protocol with the values of the context
and uri
arguments.
ddFileName <String>
Specifies the oracle-webservices.xml
deployment descriptor that contains the settings you want to assign to the Web service. If this argument is not used, then an oracle-webservices.xml
deployment descriptor will be generated.
When this argument is used with the *Assemble
commands, management and custom serialization information will be copied from the specified file to the oracle-webservices.xml
file in the archive.
If the specified file name cannot be found, WebServicesAssembler will stop processing.
The appendToExistingDDs
and the ddFileName
arguments can be used in the same command line invocation or Ant task.
See Also:
|
uri <String>
Specifies the URI to use for the Web service. This is the third part of the URL used to contact the Web service. The first part is the protocol, which is set at deployment time. The second part is provided by the context
argument. The full URL is created by concatenating the protocol, the context, and the uri arguments.
The default value for uri
is the value of the appName
argument. You cannot specify an empty string for uri
.
Using this argument adds the <url-pattern>
element to web.xml
(for Web applications) and the <endpoint-address-uri>
element to oracle-webservices.xml
for EJB 2.1.
The following arguments can be used to access the WSDL. The Http*
arguments help to access the WSDL if it is a URL and resides on a network that uses an HTTP proxy server.
fetchWsdlImports <true|false>
Indicates if you want to make a local copy of the WSDL and everything it imports. When fetchWsdlImports
is true
, the specified WSDL and everything it imports will be copied to the WAR. When false
, only the specified WSDL will be copied to the WAR. Default value is false
.
This argument is typically used when the WSDL must be packaged with the deployment. This avoids the overhead, un-reliability, security, or threat-of-change issues that may arise when calling out for each runtime invocation requires a remote schema. The only time you would package a WSDL and its schema imports with a Web service is in a top down assembly.
httpNonProxyHosts <String>
Specifies the name of the host that should not use an HTTP proxy. If there are multiple hosts they should be separated by a '|
', for example localhost|127.0.0.1
. This argument can help to get the WSDL if it is a URL that resides on a network that uses an HTTP proxy server.
httpProxyHost <String>
Specifies the name of the HTTP proxy host. This argument can help to get the WSDL if it is a URL that resides on a network that uses an HTTP proxy server.
httpProxyPort <int>
Specifies the port number for the HTTP proxy. This argument can help to get the WSDL if it is a URL that resides on a network that uses an HTTP proxy server.
importAbstractWsdl <true|false>
Specifies whether the generated WSDL will import the WSDL specified with the wsdl
argument. If true
, the generated WSDL will import the WSDL file. If false
, the generated WSDL elements and the elements in the original WSDL will be written to a single output file. Default value is false
.
wsdl <String>
Specifies the absolute file path, relative file path, or URL to a WSDL document. For example, http://host:80/services/myservice?WSDL
and myservice.wsdl
are valid values for this argument.
If the network uses an HTTP proxy server, and the WSDL is a URL, you may need to set the httpNonProxyHosts
, httpProxyHost
and httpProxyPort
arguments.
The following options can be used to control the contents of the generated WSDL.
createOneWayOperations <true|false>
When this argument is set to true
, methods that return void
will have no response message. If it is not specified or set to false
, the response message will be empty. Default value is false
.
genQos <true|false>
Determines whether QOS (quality of service) information will be added to the WSDL in the form of capability assertions. Capability assertions are derived from the Web service management configuration in the oracle-webservices.xml
deployment descriptor. If you set genQos
to true
, then capability assertions will be generated into the WSDL. You must also set the ddFilename
argument to an oracle-webservices.xml
deployment descriptor that contains the Web services management configuration. The default value of this argument is false
.
See Also: "Working with Capability Assertions" in the Oracle Application Server Advanced Web Services Developer's Guide provides more information on providing capability assertions to the server- and client-side of a Web service. |
qualifiedElementForm <true|false>
Determines whether the elementFormDefault
element in each generated schema in the WSDL is set to qualified
or unqualified
.
The value of the elementFormDefault
element indicates whether locally declared elements must be qualified by the target namespace in an instance document. If the value of this element is unqualified
, then locally declared elements should not be qualified by the target namespace. If the value is qualified
, then locally declared elements must be qualified by the target namespace.
To set the value of the elementFormDefault
element to unqualified
, set the qualifiedElementForm
argument to false
. To set the value of the element to qualified
, then set the argument to true
. The default value for the qualifiedElementForm
argument is true
.
singleService <true|false>
Determines whether a single port or multiple ports will be generated for each service defined in the WSDL. If true
, WebServicesAssembler generates a single service with multiple ports (one for each port type). If false
, WebServicesAssembler generates multiple services, each with a single port. Default is false
.
soapVersion <1.1|1.2|1.1,1.2>
Specifies the SOAP version to the WSDL document. Values can be 1.1
, 1.2
, or 1.1,1.2
. Default value is 1.1
.
The "1.1,1.2
" value means that WebServicesAssembler will create two ports with two bindings. One port and binding will support version 1.1; the other port and binding will support version 1.2. Each port must be bound to a different URL. That is, you cannot support both versions concurrently with the same URL address.
targetNamespace <String>
Specifies the target namespace to be used in the generated WSDL.
The value of targetNamespace
can be either a conforming HTTP URL, a non-conforming HTTP URL, or even a URI. The value of targetNamespace
maps to a package name in the following ways:
When the target namespace is a conforming HTTP URL, then the order of the elements in it will be reversed when mapping to a Java package name. For example:
The target namespace http://hello.demo.oracle.com
will map to the package name com.oracle.demo.hello
.
When the target namespace is a non-conforming HTTP URL, then the order of the elements in it will be unchanged. For example:
The target namespace http://hello.demo.oracle
will map to the package name hello.demo.oracle
.
When the target namespace is a URN, then the value is mapped into a single identifier, with components separated by underscores ("_
"). For example:
The target namespace urn:oracle.demo.hello
will map to the identifier oracle_demo_hello
.
For best coding practices, follow these suggestions:
When the code's package name maps to a conforming HTTP URL (when reversed), then use this URL as the target namespace. For example:
For package name com.oracle.demo.hello
, use -targetNamespace
http://hello.demo.oracle.com
.
When the code's package name does not map to a conforming HTTP URL (when reversed), then use the package name unchanged as the target namespace. For example:
For package name oracle.demo.hello
, use -targetNamespace http://oracle.demo.hello
.
Note: Avoid using a URN as the value for thetargetNamespace argument, such as:
This will cause the service and the service elements to be mapped to two different locations. The service will be mapped to For other ways in which the service and service elements can be generated into separate directories (either intentionally or unintentionally), see "Web Service and Message Parts are Generated into Separate Directories". |
typeNamespace <String>
Specifies the type namespace to be used in the schema types in the generated WSDL. The name that you specify will always be used and it will not be reversed.
See Also: "Default Algorithms to Map Between Target WSDL Namespaces and Java Package Names" for more information on this argument and the default namespace-to-package name mapping conventions. |
wsdlTimeout <int>
Specifies the number of seconds WebServicesAssembler should wait for a response to an HTTP or HTTPS request for a remote WSDL resource. The default value is 60 seconds.
By default, WebServicesAssembler will wait as long as one minute to receive the response to a HTTP request for a WSDL definition from a host. This argument is used to override the default wait limit. A value of zero indicates that WebServicesAssembler will wait for a period of time determined by the platform.
This argument applies only to requests made through HTTP or HTTPS. It will be ignored if the request is made through another protocol.
The following arguments can be used to control the message format used by the generated WSDL, and hence, the Web service.
mtomSupport <true|false>
For bottom up or top down Web service assembly, this attribute specifies whether messages with appropriate content (base64binary
) will be encoded as MTOM formatted attachments. The default value for this attribute is false
.
Using this attribute adds an <mtom-support>
element to the oracle-webservices.xml
file.
Note: This attribute can be used only with theassemble , genProxy , and topDownAssemble Ant tasks. It cannot be used as an argument on the WebServicesAssembler command line. |
See Also: See "Working with MTOM Encoded Attachments" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on how to use this argument. |
style <document-bare|document-wrapped|rpc>
For bottom up Web service assembly, this argument specifies the style
attribute of the message format in the generated WSDL. Possible values are document-bare
, document-wrapped
, and rpc
. The default value is document-wrapped
.
See Also: "OracleAS Web Services Message Formats" provides more information on the RPC and document (wrapped and bare) message styles. |
use <literal|encoded>
For bottom up Web service assembly, this argument specifies the use
attribute of the message format in the generated WSDL. Possible values are literal
and encoded
. The default value is literal
.
See Also: "OracleAS Web Services Message Formats" provides more information on the literal and encoded message uses. |
The following options can be used to control how Java files are generated.
dataBinding <true|false>
If true
, WebServicesAssembler will attempt to generate Java value types that follow the JAX-RPC default type mapping rules for every element in the schema. If WebServicesAssembler encounters an unsupported type, it will use the javax.xml.soap.SOAPElement
to represent it. If false
, WebServicesAssembler uses a SOAPElement
for every schema type it encounters. Default value is true
.
Note: OracleAS Web Services does not support the combination of RPC-encoded message formats anddatabinding=false . This combination is not considered a "best practice" within the industry. |
mapHeadersToParameters <true|false>
Indicates if SOAP headers defined in the WSDL should be mapped to parameters for each of the methods in the generated Java code. Default value is true
.
overwriteBeans <true|false>
Indicates if beans should be generated for schema types even if the class already exists in the classpath. Default value is false
.
unwrapParameters <true|false>
This argument can be set only for document-literal operations and will be ignored for other message formats. Typically a document-literal operation has a single input schema type and a single output schema type. The schema types are sometimes called wrappers. When unwrapParameters
is set to false
the generated service endpoint interface will be generated with wrappers around the input parameter and the return type. For example, a method with wrapped parameters may look like this.
public EchoResponse echo(EchoRequest p) throws RemoteException;
When unwrapParameters
is set to true
, which is the default, the return type and response type will be unwrapped. This is usually easier to use, especially if the types are simple. For example, a method with unwrapped parameters may look like this.
public String echo(String string) throws RemoteException;
valueTypeClassName <String>
Specifies the fully-qualified class name of the JAX-RPC value type which is used for java.util.Collection
and java.util.Map
. This argument enables you to generate schemas for these classes since the service endpoint interface does not refer to them directly.
See Also: "Oracle Specific Type Support" provides an example of using |
The valueTypeClassName
argument can be used multiple times on the command line or in an Ant task. In an Ant task, write the multiple occurrences in separate tags and use the name
attribute. Example 18-4 illustrates the use of multiple instances of valueTypeClassName
to generate schemas for the tClass1
, tClass2
, and tClass3
type classes.
Example 18-4 Multiple Instances of valueTypeClassName in an Ant Task
<oracle:assemble appName="myService" output="build" input="myservice.jar" style="rpc" use="encoded"> <oracle:porttype interfaceName="com.myCompany.myService.Hello" className="com.mycompany.HelloImpl"/> <oracle:valueTypeClassName name="tClass1"/> <oracle:valueTypeClassName name="tClass2"/> <oracle:valueTypeClassName name="tClass3"/> </oracle:assemble>
valueTypePackagePrefix <String>
Specifies the package name prefix for all value types that are to be created from a WSDL. This argument enables you to group value type package names by service.
All value type classes will start with the specified package name. By default, the package name for value types is based on the namespace of the complex type in the schema. This argument can be used to prefix the package name that is derived from the namespace.
For example, if valueTypePackagePrefix
is set to myapp
, and the type's target namespace is http://ws-i.org/
, then the package name will be myapp.org.ws-i
.
If you need more control over the WSDL namespace to Java package mapping, then use a JAX-RPC mapping file. The valueTypePackagePrefix
argument is ignored if there is a namespace to package mapping defined in the JAX-RPC mapping file.
See Also:
|
wsifEjbBinding <true|false>
This argument is used in bottom up Web services assembly to add WSIF EJB bindings to the WSDL. If true
, you must also specify the EJB's home interface className
and jndiName
. WebServicesAssembler will generate native WSIF EJB bindings in addition to SOAP bindings in the WSDL. The default value is false
.
See Also:
|
The wsifEjbBinding
, wsifJavaBinding
, and wsifDbBinding
arguments are mutually exclusive. An exception will be thrown if two or more of these arguments are used in a single command line or Ant task.
wsifJavaBinding <true|false>
This argument is used in bottom up Web services assembly to add WSIF Java bindings to the WSDL. If true
, you must also specify the className
of the Java implementation class. WebServicesAssembler will generate native WSIF Java bindings in addition to SOAP bindings in the WSDL. The default value is false
.
See Also:
|
The wsifEjbBinding
, wsifJavaBinding
, and wsifDbBinding
arguments are mutually exclusive. An exception will be thrown if two or more of these arguments are used in a single command line or Ant task.
The WSDL 1.1 specification allows various element definitions to have the same name within a specified namespace in the WSDL document. This can potentially cause name conflicts when mapping from WSDL to Java.
Section 4.3.12 of the JAX-RPC specification outlines the rules to resolve name collisions by appending suffixes to the mapped Java identifiers. The following commands make use of these rules when generating Java files:
Table 18-5, contains content copied from the JAX-RPC specification for your convenience. It specifies rules and suffixes for avoiding name collisions in the WSDL to Java mapping. If there are no name collisions, then there is no requirement to use these suffixes.
Table 18-5 Name Collision Rules
Java Definition mapped from WSDL/XML | Appended Suffix in the Mapped Java Identifier | Examples |
---|---|---|
Java class based on the WSDL/XML to Java type mapping whose name is derived from that of a |
|
XML: Java: |
Java enumeration class (see Section 4.2.4 of the JAX-RPC specification) |
|
XML:
Java: |
Java class based on the WSDL/XML to Java type mapping whose name is derived from that of a |
|
XML: Java: |
service endpoint interface |
|
XML:
Java: service endpoint interface: |
generated service interface |
|
XML: Java: |
exception class |
|
Java: |
The following sections describe the default algorithms that WebServicesAssembler uses to map between namespaces and package names.
The WebServicesAssembler constructs a default type namespace from the package name. If the package name starts with a standard top-level domain name or an International Organization for Standardization (ISO) country code, the WebServicesAssembler "reverses" the package name and places it into an HTTP URL. Otherwise, the package name is directly placed into an HTTP URL.
Note: The standard top level domain names are defined by the Internet Corporation For Assigned Names and Numbers (http://www.icann.org/tlds/ ).
ISO Country codes are defined by the International Organization for Standardization ( |
For example, the package com.oracle.mytypes
will have the type namespace http://mytypes.oracle.com/
. The package examples.chapter1
will have the type namespace http://examples.chapter1/
.
The following sections describe the order in which the mapping algorithm in WebServicesAssembler attempts to map Java artifacts and types to WSDL artifacts and XML schema types.
The following steps represent the order in which the WebServicesAssembler tool attempts to map Java artifacts to WSDL artifacts.
Use the value of the targetNamespace
WebServicesAssembler argument to get the target namespace to be used in the generated WSDL. See "targetNamespace" for more information on this argument.
Look up the value of the Java <package-mapping>
element in the JAX-RPC mapping file.
Derive the name of the WSDL namespace from the Java package name of the service endpoint interface.
The following steps represent the order in which the WebServicesAssembler tool attempts to map Java types to XML schema types.
Look up the value of the Java <package-mapping>
element in the JAX-RPC mapping file.
Use the value of typeNamespace
WebServicesAssembler argument to get the type namespace for the schema types in the generated WSDL. See "typeNamespace" for more information on this argument.
Derive the WSDL namespace from the Java package of the value type.
Use the value of the targetNamespace
attribute defined in the WSDL.
The WSDL namespace to Java package name mapping is based on the algorithm in the Java Architecture for XML Data Binding (JAXB) specification, version 2.0. This specification can be found at the following Web site:
http://www.jcp.org/en/jsr/detail?id=222/
The following are exceptions to the algorithm defined in the specification:
The algorithm in the JAXB specification states that the scheme part of the URI should be removed only if it is either http
or urn
. The current implementation has expanded the set of schemes to remove. The set includes the following: http
, https
, ftp
, mailto
, file
, nntp
, telnet
, ldap
, nfs
, urn
, and tftp
.
The algorithm in the JAXB specification does not specify what action to take when Globalization Support characters are present in the URI. In the current implementation, any non-ASCII characters are encoded in the form u
xxxx, where xxxx is the four-digit UTF8 encoding.
The JAXB specification states that Step 6 of the algorithm should be skipped if the top-level domain name is not a standard country code or top level domain name. The specification does not further clarify what processing should be done in this case. In the current implementation, the host string of the URI is tokenized with the delimiter ".", even when the string does not end with a top-level domain name or country code.
Table 18-6 lists some examples of package name to namespace mappings.
Table 18-6 Examples of Namespace to Package Name Mappings
Namespace | Package Name |
---|---|
http://army.mil/ |
mil.army |
http://oracle/j2ee/ws_example/ |
oracle.j2ee.ws_example |
http://somecompany.jp/ |
jp.somecompany |
http://toplink.oracle.com |
com.oracle.toplink |
http://www.acme.com/go/espeak.xsd |
com.acme.go.espeak |
urn:dime/types.xsd |
dime.types_xsd |
The following sections describe the order in which the mapping algorithm in WebServicesAssembler attempts to map the service endpoint interface, value types, and their related artifacts in the WSDL to Java names and types.
The following steps represent the order in which the WebServicesAssembler tool attempts to map the service endpoint interface and its related artifacts in the WSDL to Java names.
For the service endpoint interface, look up the value of the <service-interface-mapping>
element in the JAX-RPC mapping file. See "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on this file.
Use the value of the packageName
WebServicesAssembler argument to get the Java package name for the generated classes. See "packageName" for more information on this argument.
Look up the value of the <package-mapping>
element in the JAX-RPC mapping file.
Derive the Java package name from WSDL namespace.
The following steps represent the order in which the WebServicesAssembler tool attempts to map the value types and their related artifacts in the WSDL to Java names and types.
Look up the <java-xml-type-mapping>
element in the JAX-RPC mapping file. See "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on this file.
If the schema type is defined under the same namespace as the targetNamespace
of the targeting document (a WSDL or schema), then use the value of the packageName
WebServicesAssembler argument. See "packageName" for more information on this argument.
Look up the value of the Java <package-mapping>
element in the JAX-RPC mapping file.
Derive the Java package name from the WSDL namespace and the value of the valueTypePackagePrefix
WebServicesAssembler argument as described in "valueTypePackagePrefix". See also "How to Specify a Root Package Name" for more information on this argument.
Use the typeNamespace
argument to explicitly specify a namespace. The name that you specify will always be used and it will not be reversed.
Use the valueTypePackagePrefix
argument to specify a root package name for all types in the schema(s) in the specified WSDL. All package names will start with this value. The specified value will be used only if there is no type namespace-to-package mapping declared in the JAX-RPC mapping file.
If the generated package name starts with the same value, it will not be added to the package name. This will avoid packages looking like com.oracle.mytypes. com.oracle.mytypes
.
The aqAssemble, dbJavaAssemble, plsqlAssemble, and sqlAssemble commands require a database connection to generate a Web service. A connection can be made to the database at Web service assembly time and at runtime. At Web service assembly time, the WebServicesAssembler connects to the database to get information on the database entities such as PL/SQL packages or AQ queues. At Web service runtime, the user application uses the data source JNDI location to get the JDBC connection for database operations. WebServicesAssembler ensures that this information will be provided to the Web service runtime code.
The following arguments can be used to provide connection information to a Web service.
To provide assembly time and runtime access to the database, use either the dataSource
argument or the dbConnection
and dbUser
combination on the command line or in an Ant task.
The dbConnection
and dbUser
arguments usually appear together. They provide the JDBC URL and the database schema and password to WebServicesAssembler for assembly time and runtime access to the database.
The dataSource
argument provides the JNDI location that allows WebServicesAssembler to provide assembly time and runtime access to the database.
If all three arguments appear in an Ant task or on the command line, then the values of dbConnection
and dbUser
will be used for assembly time access and dataSource
will be used for runtime access to the database.
This section describes additional functionality that is available for WebServicesAssembler through Ant tasks. This functionality is not available on the WebServicesAssembler command line.
The following arguments to WebServicesAssembler commands can be declared more than once on the command line or in an Ant task.
In an Ant task, you must list multiple instances of any of these arguments as separate tags. When they are listed as separate tags, the input
, schema
, and sqlstatement
arguments require a value
attribute. The valueTypeClassName
argument requires a name
attribute.
For example, the following assemble
command uses multiple instances of the input
argument to generate an EAR file which includes first.jar
, second.jar
, and third.jar
.
<oracle:assemble appName="myService" output="build"> <oracle:PORTTYPE interfaceName="com.myCompany.myService.Hello" className="com.mycompany.HelloImpl"> </oracle:porttype> <oracle:input value="first.jar"/> <oracle:input value="second.jar"/> <oracle:input value="third.jar"/> </oracle:assemble>
The following jmsAssemble
command uses multiple instances of the valueTypeClassName
argument to identify class names of the JAX-RPC value types which can be items in java.util.Collection
and java.util.Map
.
<oracle:jmsAssemble linkReceiveWithReplyTo="true" targetNamespace="http://oracle.j2ee.ws/jms-doc" typeNamespace="http://oracle.j2ee.ws/jms-doc/types" serviceName="JmsService" appName="jms_service" context="jms_service" input="./demo/build/mdb_service.jar" output="./demo/dist" > <oracle:valueTypeClassName name="tClass1"/> <oracle:valueTypeClassName name="tClass2"/> <oracle:valueTypeClassName name="tClass3"/> </oracle:jmsAssemble>
The proxy
subtag enables you to generate a client proxy at the same time the server code is assembled. This is most useful during bottom up assembly when the name of the WSDL is not necessarily known ahead of time. You can use the proxy
subtag in Ant tasks for the following commands.
The proxy
subtask provides functionality similar to the genProxy
WebServicesAssembler command. Except for wsdl
, any of the supported genProxy
arguments can be used as attributes in the proxy
subtag.
The output
argument is supported as an attribute, but is not required as it is for genProxy
. If output
is not specified in the proxy
subtag, then the value of output
provided for the parent tag will be used with the src/proxy
directory path appended to it. For example if the parent tag sets output="build"
, then the output for the proxy subtag will be placed in build/src/proxy
.
The following arguments can be used as attributes to the proxy subtag.
Example 18-5 illustrates the use of a <proxy>
subtag with a packageName
attribute. In this example, assemble
is used as the parent tag.
Example 18-5 Using the proxy Subtag in an Ant Task
<oracle:assemble...> (or any command that supports the proxy tag)
<oracle:proxy packageName="myproxy"/>
</oracle:assemble>
You can add message processing information and port-specific information to a proxy by using the <handler>
and <port>
tags.
<handler>
—to examine and potentially modify a request before it is sent to the remote host, or before the client processes the response, you can configure a <handler>
tag as a sub tag of <proxy>
. "How to Configure Handlers in an Ant Task" provides more information on the <handler>
tag.
<port>
—to generate a proxy for a particular port, you can configure a <port>
tag as a sub tag of <proxy>
. "How to Configure a Port in an Ant Task" provides more information on the <port>
tag.
The port identifies the network address of the endpoint hosting the Web service. For some WebServiceAssembler commands, Ant tasks allow you to specify a port
tag as a child. This enables you to have a different configuration for each port. For example, you can assign two different transports or two different SOAP versions.
These Ant tasks allow you to specify a port
tag.
These arguments can be used in a port
tag (note: arguments in the context of Ant tasks are "attributes").
portName (or name)
In addition to these arguments, the port
tag also enables you to specify a name
argument which is the local part of the port name.
Within the port
tag, each command can specify zero or more optional arguments. Each command supports a different subset of arguments. For the list of arguments that can be used for a particular command, see the command's "Additional Ant Support" section.
Example 18-6 illustrates using the port
tag to specify a JMS and an HTTP transport to different ports. Note that the port
declaration for the HTTP transport uses the name
attribute. The name
attribute is optional if you specify only one port
in an Ant task. If you specify multiple port
tags in an Ant task, then the name
attribute is required.
Example 18-6 Assigning Different Transports to Different Ports
<oracle:port uri="/echo" sendQueue="jms/senderQueue" sendConnectionFactoryLocation="jms/senderQueueConnectionFactory" replyToConnectionFactoryLocation="jms/receiverQueueConnectionFactory" replyToQueue="jms/receiverQueue"/> <oracle:port uri="echo2" name="EchoHttpPort"/>
Example 18-7 illustrates using the port
tag to specify different SOAP message versions to different ports. When you specify multiple ports in the same Ant task, then each port
tag will require a name
attribute:
Some Ant tasks allow you to specify a porttype
tag as a child task. This enables you to configure different interfaces to a Web service. The Ant tasks for these WebServicesAssembler commands allow you to specify porttype
as a child task:
A porttype
tag must have an interfaceName
argument to identify the interface to the Web service. If you are specifying multiple <porttype>
tags, then each tag must contain a <port>
subtag.
When configuring a porttype
with the assemble
, topDownAssemble
, genDDs
, and genWsdl
commands, you must specify a className
attribute. For the assemble
and topDownAssemble
commands, you can specify a classFileName
attribute instead of a className
attribute.
Additionally, for the topDownAssemble
command, if the WSDL contains references to multiple port types, then you must specify a <porttype>
tag for each port type.
Table 18-7 summarizes the valid attributes and subtags that can be used with the <porttype>
tag.
Table 18-7 Attributes and Subtags for the <porttype> Tag
Attributes and Subtags | Description |
---|---|
This attribute can be specified for the |
|
This attribute is required for the |
|
An |
|
A |
Example 18-8 illustrates assigning a port type to a Web service.
This section has the following subsections.
WebServicesAssembler lets you configure handlers and client handlers in Ant tasks. You can use the Ant tasks to configure all of the information defined for handlers by the Enterprise Web Services 1.1 specification.
Note: Handlers and client handlers can be declared and configured only in Ant tasks. They cannot be declared or configured on the command line. |
A handler can examine and potentially modify a request, response, or fault before it is processed by a Web service component. It can also examine and potentially modify the response or fault after the component has processed the request. A client handler, as its name implies, runs on the client before the request is sent to the remote host, and before the client processes the response.
The handler
tag defines a handler in a WebServicesAssembler Ant task. Attributes define details about the handler. These tags and attributes correspond to the <handler>
tag and its subelements defined by the Enterprise Web Services 1.1 specification. Declaring a handler and its attributes in an Ant task will set corresponding elements in webservices.xml
.
The following sections describe the attributes and child tags that can be used with the handler
tag.
class (attribute)
class="class_name"
This attribute defines a fully-qualified class name for the handler implementation.
Using this attribute sets the <handler-class>
class_name</handler-class>
element in webservices.xml
.
initparam (child tag)
<oracle:initparam name="myName" value="myValue" />
This child tag defines a name-value pair that a handler can use as an initialization parameter. The name
attribute contains the name of a parameter. Each parameter name must be unique in the Web application. The value
attribute contains the value of the corresponding parameter.
You can define multiple initparam
declarations as children of a handler
Ant task invocation.
Using the initparam
child tag sets the following <init-param>
structure in webservices.xml
.
<init-param> <param-name>myName</param-name> <param-value>myValue</param-value> </init-param>
name (attribute)
name="handler_name"
This attribute defines the name of the handler. The name must be unique within the module.
Using this attribute sets the <handler-name>
handler_name</handler-name>
element in webservices.xml
.
soapheader (child tag)
<oracle:soapheader value="{namespace_URI}local_part"/>
This child tag defines the QName
of a SOAP header that will be processed by the handler. The value
attribute takes a local part of a QName
and a namespace URI. You can define multiple soapheader
declarations as children of a handler
Ant task.
The value of the soapheader
child tag is written to the soap-header
tag in webservices.xml
. For example, if the namespace URI is http://oracle.j2ee.ws/Header
and the local part is authenticateHeader
, then the soapheader
child tag has the following value.
<oracle:soapheader value="{http://oracle.j2ee.ws/Header}authenticateHeader"/>
This value will have the following representation in the webservices.xml
file.
<soap-header xmlns:wsa1="http://oracle.j2ee.ws/Header">wsa1:authenticateHeader</soap-header>
In this example, wsa1
is a unique prefix for the given namespace.
soaprole (attribute)
soaprole ="Some_SoapRole"
This attribute defines a SOAP actor that the handler will play as a role.
Using this attribute sets the <soap-role>
Some_SoapRole
</soap-role>
element in webservices.xml
.
soapRole (child tag)
This child tag has the same behavior as the soaprole
attribute: it defines a SOAP-actor that the handler will play as a role. However, unlike the attribute, the soapRole
child tag enables you to specify more than one SOAP role for the handler.
For example, the following Ant task fragment uses the soapRole
subtag to define two SOAP actors that the handler will play as a role.
... <oracle:handler soapRole="SomeSOAPRole" name="StaticStateHandlerName" class="oracle.j2ee.ws.tools.wsa.handler.StaticStateHandler"> <oracle:soapRole name="another-soap-role"/> <oracle:soapRole name="yet-another-soap-role"/> </oracle:handler> ...
To illustrate how to construct a handler configuration that can be used in an Ant task, Example 18-9 provides a sample configuration for the StaticStateHandlerName
handler. The handler in implemented by the myApp.handler.StaticStateHandler
class, and it requires two initialization parameters, SCOTT
and TIGER
. The handler will process two types of SOAP headers: authenticateHeader
and authenticateHeader2
.
Example 18-9 A Sample Handler Configuration
<some tag that supports handlers> <oracle:handler soaprole="Some_SoapRole" name="StaticStateHandlerName" class="myApp.handler.StaticStateHandler"> <oracle:initparam name="id" value="SCOTT"/> <oracle:initparam name="password" value="TIGER"/> <oracle:soapheader value="{http://oracle.j2ee.ws/Header}authenticateHeader"/> <oracle:soapheader value="{http://oracle.j2ee.ws/Header2} authenticateHeader2"/> </oracle:handler> </some tag that supports handlers>
The Ant tasks for the following WebServiceAssembler commands allow you to specify a handler
tag as a child task.
genDDs (can specify a handler
tag for the server side only)
You can specify multiple handlers for any command that supports handlers. Each handler can have a different configuration.
Example 18-10 illustrates a multiple handler configuration. The parent tag can be any tag which supports handlers.
The first handler tag configures the StaticStateHandlerName
handler. The handler is implemented by the myApp.handler.StaticStateHandler
class, and it requires two initialization parameters, SCOTT
and TIGER
. The handler will process two types of SOAP headers: authenticateHeader
and authenticateHeader2
.
The second handler tag shows a very basic handler tag. It configures the MyOtherHandler
handler that is implemented by the myapp.handler.MyOtherHandler
class.
Example 18-10 Sample Multiple Header Configuration
<some tag that supports handlers> <handler soaprole="Some_SoapRole" name="StaticStateHandlerName" class="myApp.handler.StaticStateHandler"> <initparam name="id" value="SCOTT"/> <initparam name="password" value="TIGER"/> <soapheader namespace="http://oracle.j2ee.ws/Header" localpart="authenticateHeader"/> <soapheader namespace="http://oracle.j2ee.ws/Header2" localpart="authenticateHeader2"/> </handler> <handler name="MyOtherHandler" class="myApp.handler.MyOtherHandler"/> </some tag that supports handlers>
To add a file to an EAR or WAR archive, copy the file to the directory that WebServicesAssembler uses as a staging area where it jars the archive before calling the *Assemble
task. Figure 18-1 illustrates the layout of the staging area.
The default staging area is <
output
>/war
for a WAR archive and <
output
>/ear
for an EAR archive. The <
output>
variable indicates the value of the output
argument. For example, if the value of the output
argument is outputDir
, then the files are stored in outputDir/war
and outputDir/ear
.
For example, the following Ant task will place a key store oraks.jks
into the generated EAR.
<copy file="oraks.jks" todir="build/ear/META-INF/> <oracle:assemble output="build" ... />
WebServicesAssembler provides a boolean failonerror
argument that will allow you to continue a build even though there are errors. If the value of failonerror
is true
, the build fails if WebServicesAssembler encounters an error. If the value is false
, then the build will continue. The default value is true
.
The failonerror
argument can be used with any WebServicesAssembler command. In the following example, WebServicesAssembler will continue to process if the assemble command encounters an error.
<oracle:assemble failonerror="false" ... />
The mtomSupport
Ant attribute enables you to assemble support for MTOM encoded messages into a Web service and Web service client. You can use this attribute only in Ant tasks; is is not available on the WebServicesAssembler command line.
The mtomSupport
attribute can be used with these Ant tasks:
See Also: For more information on the
|
To assign multiple Web services in a single archive (EAR or WAR) the assemble
or topDownAssemble
task must be called for each Web service that is going in the WAR. The arguments defined for each assemble task must follow these rules.
All output
arguments must have the same value. Only the last assemble
task can define an ear
argument. The reason for this is when an ear
argument is specified, the contents of the WAR staging directory (/war
) will be archived and put in the EAR. When an archive is created, the files in the staging area are deleted.The war
argument for all tasks except the last, must have the same value as the output
argument with the directory name /war
appended to it. This is because WebServicesAssembler's default behavior is to use the output directory, directory
/war
, as the staging area for the WAR. For example, if the output
argument is set to dist
then the war
argument should be set to dist/war
.All tasks except the first must set appendToExistingDDs
to true
. The first assemble
task can set appendToExistingDDs
to true
only if the output directory
/war
, already contains deployment descriptors that you want WebServicesAssembler to modify (for example a web.xml
with resource references). The last assemble
task should not define a war
argument unless you want WebServicesAssembler to create a WAR instead of an EAR.The appName
argument must be unique in all of the assemble
tasks.
If a uri
argument is specified it must be unique in all of the assemble
tasks.
Example 18-11 displays the Ant tasks to assign two Web services, firstApp
and nextApp
to the myApps.ear
EAR file. Note the following details in the example code.
the output
arguments for the two assemble commands are assigned the same value for the output directory path: ${out.dir}
.
the first assemble
command stores its output in a /war
directory, while the last assemble
argument specifies the EAR file that will store the two Web services.
the last Web service specifies the appendToExistingDDs
so that its deployment descriptor will be appended to the descriptor generated by the previous command.
The ellipsis indicates additional Ant commands.
Example 18-11 Ant Tasks to Assign Two Web Services to an EAR
<oracle:assemble appName="firstApp" output="${out.dir}" war="${out.dir}/war" ... /> <oracle:assemble appName="nextApp" output="${out.dir} appendToExistingDDs="true" ear="myApps.ear" ... />
Example 18-12 displays the Ant tasks to assign three Web services, firstApp
, nextApp
, and lastApp
to the myApps.ear
EAR file. Note the following details in the example code.
the output
arguments for the three assemble
commands are assigned the same value for the output directory path: ${out.dir}
.
the first two assemble
commands store their output in a /war
directory, while the last assemble
argument specifies the EAR file that will store the three Web services.
the second and last Web services also specify the appendToExistingDDs
so that their deployment descriptors will be appended to the descriptor generated by the previous command.
The ellipsis indicates additional Ant commands.
Example 18-12 Ant Tasks to Assign Three Web Services to an EAR
<oracle:assemble appName="firstApp" output="${out.dir}" war="${out.dir}/war" ... /> <oracle:assemble appName="nextApp" output="${out.dir} appendToExistingDDs="true" war="${out.dir}/war" ... /> <oracle:assemble appName="lastApp" output="${out.dir} appendToExistingDDs="true" ear="myApps.ear" ... />
WebServicesAssembler does not check for conflicts when adding multiple Web services to a single WAR. The following conflicts will cause an invalid assembly that will not be detected until deployment time or runtime.
The different Web services contain WSDL files that have the same name.
If the WSDL files in different Web services have the same name, then one of the WSDL files will overwrite the others. To avoid this conflict, ensure that WSDL file names in different Web services are unique.
The different Web services contain class files that have the same name.
If class files use the same name (including package name) in different Web services, then one of the classes will overwrite the other. In some cases, these files really are the same. For example, value type classes from the same schema types can be shared between two different services. This type of conflict will not cause a problem.
Classes that cannot be the same include the service endpoint interface and the implementation class. If the class files are not the same, then they should either be renamed or placed in a different package.
When you are generating a Web service bottom up from Java classes or EJBs, WebServicesAssembler generates a WSDL. For a Java method's <element name="..." />
attribute in the generated WSDL, WebServicesAssembler attempts to use the method's actual parameter names. Using the method's actual parameter names in the WSDL and SOAP messages makes it easier for you to determine which parameter corresponds to which element.
WebServicesAssembler uses these techniques to attempt to retrieve the method's parameter names in the following order.
If the interface source file is provided, WebServicesAssembler will parse the code for parameter names. To do this, the full path name of the Java interface file must be specified with the interfaceFileName
argument.
If the interface source file is not provided, WebServicesAssembler will attempt to load and parse the Java class file that implements the methods in the interface. To be able to extract the parameter names, the class file must have been compiled with the -g
option to javac
.
If these techniques fail to retrieve the parameter names, or if the class is not loadable or obfuscated, then WebServicesAssembler uses the parameter's datatype and a number (for example, string_1
) by default.
Example 18-13 and Example 18-14 provide WSDL fragments that represent the following method.
public String sayHello(String name)
Example 18-13 illustrates a WSDL fragment where WebServicesAssembler was able to retrieve the sayHello
method's parameter name. The <element name="..."/>
attribute and its value are highlighted in bold.
Example 18-13 WSDL Fragment With a Generated Parameter Name
<definitions name="HelloService" targetNamespace="http://hello.demo.oracle/">
<types>
<schema elementFormDefault="qualified" targetNamespace="http://hello.demo.oracle/">
<complexType name="sayHello">
<sequence>
<element name="name" nillable="true" type="string"/>
</sequence>
</complexType>
...
Example 18-14 illustrates a WSDL fragment where the sayHello
method's parameter name could not be determined. WebServicesAssembler uses string_1
value for the element name attribute. The <element name="..."/>
attribute and its value are highlighted in bold.
Example 18-14 WSDL Fragment With a Default Parameter Name
<definitions name="HelloService" targetNamespace="http://hello.demo.oracle/">
<types>
<schema elementFormDefault="qualified" targetNamespace="http://hello.demo.oracle/">
<complexType name="sayHello">
<sequence>
<element name="string_1" nillable="true" type="string"/>
</sequence>
</complexType>
...
For more information on:
assembling Web services from a WSDL, see Chapter 6, "Assembling a Web Service from WSDL".
assembling stateful Web services, see Chapter 7, "Assembling a Web Service with Java Classes".
assembling Web services from EJBs, see Chapter 8, "Assembling a Web Service with EJBs".
assembling Web services from a JMS queue or topic, see Chapter 9, "Assembling Web Services with JMS Destinations".
assembling Web services from database resources, see Chapter 10, "Assembling Database Web Services".
assembling Web services with J2SE 5.0 Annotations, see Chapter 11, "Assembling Web Services with Annotations".
assembling REST Web services, see Chapter 12, "Assembling REST Web Services".
building J2EE clients, see Chapter 14, "Assembling a J2EE Web Service Client".
building J2SE clients, see Chapter 15, "Assembling a J2SE Web Service Client".
packaging and deploying Web services, see Chapter 19, "Packaging and Deploying Web Services".
JAR files that are needed to assemble a client, see Appendix A, "Web Service Client APIs and JARs".
Web services interoperability, see "Ensuring Interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.
using quality of service features in Web service clients, see "Managing Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.
adding security to a Web service, see the Oracle Application Server Web Services Security Guide.
how to write clients to access Web services secured on the transport level, see "Adding Transport-level Security for Web Services Based on EJBs" and "Accessing Web Services Secured on the Transport Level" in the Oracle Application Server Web Services Security Guide.
adding reliability to a Web service, see "Ensuring Web Service Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide.
adding an auditing and logging configuration to a Web service, see "Auditing and Logging Messages" in the Oracle Application Server Advanced Web Services Developer's Guide.
processing nonstandard data types, see "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide.
using the JAX-RPC mapping file and its contents, see "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide.
data types supported by OracleAS Web Services, see "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide.
using the Web Service Invocation Framework, see "Using Web Services Invocation Framework" in the Oracle Application Server Advanced Web Services Developer's Guide.
Oracle JDeveloper tool support for Web service development, see the Oracle JDeveloper on-line help.