Skip Headers
Oracle® Application Server Web Services Developer's Guide
10g (10.1.3.5.0)
Part Number E13982-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

18 Using WebServicesAssembler

This chapter describes the functionality provided by the WebServicesAssembler tool.

About the WebServicesAssembler Tool

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.

Command Line Syntax

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.

Setting Up Ant for WebServicesAssembler

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.

WebServicesAssembler Commands

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

The following commands can be used to assemble a Web service.

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 the war 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:

  • specify a different output directory for each invocation of WebServicesAssembler

  • delete the contents of the output directory in between calls to the WebServicesAssembler invocations

Figure 18-1 Staging Directory Structure Created by the *Assemble Commands

Described in the surrounding text.
Description of "Figure 18-1 Staging Directory Structure Created by the *Assemble Commands"

aqAssemble

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.

All Arguments:

The following list identifies all of the arguments that can be used with the aqAssemble command.

Ant Task Support:

assemble

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:

  • "Configuring a WSIF Endpoint for Multiple Java Ports" in the Oracle Application Server Advanced Web Services Developer's Guide.

  • "Using Web Services Invocation Framework" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on WSIF.

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.

All Arguments

The following list identifies all of the arguments that can be used with the assemble command.

Ant Task Supports:

corbaAssemble

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.

All Arguments:

The following list identifies all of the arguments that can be used with the corbaAssemble command.

Ant Task Support:

dbJavaAssemble

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:

  • "How to Assemble a Server-Side Java Class as a Web Service" provides more information on using the dbJavaAssemble command to generate Web services from a Java class inside the Java VM in an Oracle database.

  • "How to Establish a Database Connection" describes the arguments that allow you to connect to a database.

  • "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 -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.

Ant Task Support:

ejbAssemble

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 the ejbAssemble 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:

  • "ear" for a description of the different ways in which you can specify this parameter.

  • "Using Web Services Invocation Framework" in the Oracle Application Server Advanced Web Services Developer's Guide provides more information on WSIF.

  • "Configuring a WSIF Endpoint for EJBs" in the Oracle Application Server Advanced Web Services Developer's Guide provides information on adding WSIF bindings for individual and for multiple ports.

  • Chapter 8, "Assembling a Web Service with EJBs" provides more information on using the ejbAssemble command to expose a version 2.1 EJB as a Web service.

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.

Additional Ant Support:

jmsAssemble

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 jmsAssemble command to expose a JMS destination as a Web service.

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.

All Arguments:

The following list identifies all of the arguments that can be used with the jmsAssemble command.

Ant Task Supports:

plsqlAssemble

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.

Ant Task Support:

sqlAssemble

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.

All Arguments:

The following list identifies all of the arguments that can be used with the sqlAssemble command.

Ant Task Support:

topDownAssemble

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 topDownAssemble command to generate a Web service based on a WSDL description.

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.

Additional Ant Support:

WSDL Management Commands

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

analyze

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:

The analyze 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.

Additional Ant Support:

None

fetchWsdl

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.

Additional Ant Support:

None

genConcreteWsdl

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.

Additional Ant Support:

None.

genQosWsdl

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.

Additional Ant Support:

None

genWsdl

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.

Additional Ant Support:

Java Generation Commands

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

genInterface

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 the genInterface command for the schema types under these conditions:

  • the class name, including the package name, already exists in the classpath argument given to the WebServicesAssembler command, and

  • the command line argument overwriteBeans is set to false (the default value). See "overwriteBeans".

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 <portTypeName> element in the WSDL document. Section 4.3.3, "WSDL Port Type", in the JAX-RPC 1.1 specification, describes this class.

Note:

The genInterface 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 dataBinding argument to false when generating the interface. For more information, see "genInterface, genProxy, and topDownAssemble Cannot Process WSDL Files Correctly that Contain Multibyte Characters in Element Names".

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.

Additional Ant Support:

None

genProxy

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 the genProxy command for the schema types under these conditions:

  • the class name, including the package name, already exists in the classpath argument given to the WebServicesAssembler command, and

  • the command line argument overwriteBeans is set to false (the default value). See "overwriteBeans".

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 <portName> element in the WSDL document.

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 <portTypeName> element in the WSDL document. Section 4.3.3, "WSDL Port Type", in the JAX-RPC 1.1 specification, describes this class.

<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 <serviceName> element in the WSDL. Sections 4.3.9, "WSDL Service", and 4.3.10, "Service Interface" describe this class.

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.

Additional Ant Support:

genValueTypes

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.xml 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:

  • "Editing the Server Side Custom Type Mapping File" in the Oracle Application Server Advanced Web Services Developer's Guide for an example of an edited service side custom type mapping file.

  • "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on the custom serializer.

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.

Additional Ant Support:

None

Deployment Descriptor Generation Commands

The following commands create deployment descriptors or files that are used in generating descriptors for the EAR.

genApplicationDescriptor

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.

Additional Ant Support:

None

genDDs

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.

All Arguments:

The following list identifies all of the arguments that can be used with the genDDs command.

Additional Ant Support:

Maintenance Commands

The following commands return a short description of WebServicesAssembler commands and the version number of the tool.

  • help—Returns a list of WebServicesAssembler commands

  • version—Returns the version of the WebServicesAssembler tool

help

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:

Additional Ant Support:

None

version

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:

Additional Ant Support:

None

WebServicesAssembler Arguments

This section describes the arguments that can be called for WebServicesAssembler commands.

General Web Services Assembly Arguments

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

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.

bindingName

bindingName <String>

The name of the binding to use in the generated WSDL.

classFileName

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

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.

See Also:

"ejbAssemble" for more information on using this command with the className argument

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

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.

See Also:

"input" for more information on this 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

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

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 the ear 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

ear directory1

war directory2

If the ear and war arguments are set to different directories, the following behavior will occur:

  • no .ear file will be created

  • the contents of the .ear file will be generated into directory1

  • a .war file will be created in directory1

  • the contents of the .war file will be generated into directory2

ear directory1

war file

If the ear argument is set to a directory and the war argument is set to a file, the following behavior will occur:

  • no .ear file will be created

  • the contents of the .ear file will be generated into directory1

  • a .war file will be created in directory1

  • a .war file will be created with the user-specified name (the value of the file parameter)

ear file

war directory2

If the ear argument is set to a file and the war argument is set to a directory, the following behavior will occur:

  • a .ear file will be created with the user-specified name (value of the file parameter)

  • a .war file will be created in the .ear file

  • the contents of the .war will be generated into directory2

ear file1

war file2

If the ear argument is set to a file and the war argument is set to a file, the following behavior will occur:

  • a .ear file will be created with the user-specified name (value of the file1 parameter)

  • a .war file will be created in the .ear file

  • a .war file will be created with the user-specified name (the value of the file2 parameter)

ear argument not specified

war argument not specified

If neither the ear nor the war argument are specified, the following behavior will occur:

  • a .ear file will be generated with the default name application_name.ear

  • a .war file will be generated with the default name application_name_web.war

In these examples, application_name represents the value of the appName argument.

ejbName

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

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

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

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

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

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

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.

jndiName

jndiName <String>

Specifies a JNDI name for an EJB.

jndiProviderURL

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

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

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.

See Also:

"ear" and "war" for more information on the behavior of output when it is used with these arguments.

Note:

If you specify the same directory for the output and the ear (or war) argument, then WebServicesAssembler will return an error.

packageName

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:

The packageName 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

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

portTypeName <String>

Specifies the name of the port type to use in the generated WSDL. This argument populates the <portType name="..."> WSDL element.

restSupport

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

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.

See Also:

"mappingFileName" for information on specifying a 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.

Example 18-2 Multiple Instances of schema in an Ant Task

<oracle:genValueTypes packageName="com.mycompany" 
              output="build"> 
                   <oracle:schema value="otherSchema.xsd"/>
                   <oracle:schema value="mySchema.xsd"/>
 </oracle:genValueTypes>

searchSchema

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

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

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

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 the useDimeEncoding 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

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 the war and the output argument, then WebServicesAssembler will return an error.

See Also:

  • "ear" for a description of how WebServicesAssembler interprets values for the ear argument.

  • Table 18-3 for a description of the behavior of the war and ear arguments when they are used together in the same command line or Ant task.

Session Arguments

These arguments can be used to control the behavior of session state.

callScope

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

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

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

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.

CORBA Assembly Arguments

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

corbanameURL <String>

Specifies a URL for locating the CORBA object using a CORBA Naming Service.

corbaObjectPath

corbaObjectPath <String>

Specifies a path to the CORBA object.

idlFile

idlFile <String>

Specifies the location of the CORBA idl file.

idlInterfaceName

idlInterfaceName <String>

Specifies the name of the interface in the idl from which the Web service will be generated.

idljPath

idljPath <String>

Specifies the path to the directory containing the IDL-to-Java compiler (idlj) if it is not already specified in the path.

ORBInitialHost

ORBInitialHost <String>

Specifies the host name of the ORB.

ORBInitialPort

ORBInitialPort <String>

Specifies the port for the ORB.

ORBInitRef

ORBInitRef <String>

Specifies an ORB initial reference.

Database Assembly Arguments

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.

aqConnectionFactoryLocation

aqConnectionFactory <String>

Specifies the JNDI location of the Oracle Streams AQ JMS queue connection factory for the exposed AQ.

aqConnectionLocation

aqConnectionLocation <String>

Specifies the JDNI location of the Oracle Streams AQ JMS queue connection connecting to the exposed AQ.

dataSource

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

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

dbJavaClassname <String>

Specifies the name of the server-side Java class to be published as a Web service.

dbUser

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

jpubProp <String>

Specifies the name of a file with properties to control the Oracle JPublisher translation process.

See Also:

sql

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="&quot;SIMple&quot;"

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

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

&

&amp;

"

&quot;

<

&lt;

>

&gt;

'

&apos;

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&gt;:{mysal NUMBER}"/>
</oracle:sqlAssemble>

sqlTimeout

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

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

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

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:

  • "WSIF SQL Extensions to the WSDL" in the Oracle Application Server Advanced Web Services Developer's Guide for information on the extensions the wsifDbBinding argument adds to the WSDL.

  • "Configuring a WSIF Endpoint for Multiple Database Resource Ports" in the Oracle Application Server Advanced Web Services Developer's Guide for information on arguments that allow you to more closely control the definition of the WSIF SQL bindings or to specify multiple ports.

wsifDbPort

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 wisfDbPort.

JMS Assembly Arguments

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

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

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

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.

linkReceiveWithReplyTo

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

topicDurableSubscriptionName

topicDurableSubscriptionName <String>

The value of this argument is used as a unique identity to register a durable subscription for the Topic receive operation. No default value is provided.

See Also:

The JMS specification for more information on durable subscriptions:

http://java.sun.com/products/jms/docs.html

Proxy Arguments

These arguments can be used to control the contents of the generated proxy code.

endpointAddress

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

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.

Deployment Descriptor Arguments

The following arguments can be used to control how Web service deployment is performed.

appendToExistingDDs

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 appendToExistingDDs to append a new Web service to an existing deployment descriptor.

Note:

The appendToExistingDDs and the ddFileName argument can be used in the same invocation or Ant task. The ddFileName argument points to a file that contains management configuration. All of the management configuration found in this file that corresponds to the service that is generating deployment descriptors will be included in the generated oracle-webservices.xml file. When appendToExistingDDs is false (default), then any deployment descriptor file (web.xml, oracle-webservices.xml, or webservices.xml) in the output directory will be overwritten. When appendToExistingDDs is true, WebServicesAssembler will add the entries for the current service to the existing deployment descriptor file.

Note that WebServicesAssembler does not try to resolve conflicts. If you append the same service to a deployment descriptor file twice, then an invalid deployment descriptor may be the result.

context

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.

See Also:

"uri" for an example of using the context and uri arguments to form an HTTP URL.

ddFileName

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

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.

WSDL Access Arguments

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

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

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

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

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

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

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.

WSDL Management Arguments

The following options can be used to control the contents of the generated WSDL.

createOneWayOperations

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

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

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

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

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

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 the targetNamespace argument, such as:

-targetNamespace urn:oracle.demo.hello

This will cause the service and the service elements to be mapped to two different locations. The service will be mapped to oracle_demo_hello and the service elements to oracle.demo.hello.

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

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

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.

Message Format Arguments

The following arguments can be used to control the message format used by the generated WSDL, and hence, the Web service.

mtomSupport

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 the assemble, 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

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

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.

Java Generation Arguments

The following options can be used to control how Java files are generated.

dataBinding

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 and databinding=false. This combination is not considered a "best practice" within the industry.

mapHeadersToParameters

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

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

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

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 valueTypeClassName to declare non-built-in value types as items in a Map or Collection.

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

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

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:

  • "WSIF EJB Extensions to the WSDL" in the Oracle Application Server Advanced Web Services Developer's Guide for information on the extensions that the wsifEjbBinding argument adds to the WSDL.

  • "Configuring a WSIF Endpoint for Multiple EJB Ports" in the Oracle Application Server Advanced Web Services Developer's Guide for information on arguments that allow you to more closely control the definition of the WSIF EJB bindings or to specify multiple ports.

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

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:

  • "WSIF Java Extensions to the WSDL" in the Oracle Application Server Advanced Web Services Developer's Guide for information on the extensions this argument adds to the WSDL.

  • "Configuring a WSIF Endpoint for Multiple Java Ports" in the Oracle Application Server Advanced Web Services Developer's Guide for information on arguments that allow you to more closely control the definition of the WSIF Java bindings or to specify multiple ports.

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.

Resolving Name Collisions

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 xsd:simpleType or an xsd:complexType

_Type

XML: <xsd:complexType name="shared">

Java: Shared_Type.java

Java enumeration class (see Section 4.2.4 of the JAX-RPC specification)

_Enumeration

XML:

<xsd:simpleType name="shared"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="foo"/> </xsd:restriction></xsd:simpleType>

Java: Shared_Enumeration.java

Java class based on the WSDL/XML to Java type mapping whose name is derived from that of a xsd:element

_Element

XML: <xsd:element name="shared">

Java: Shared_Element.java

service endpoint interface

_PortType

XML: <wsdl:portType name="shared">

<wsdl:binding name="shared"...>

Java: service endpoint interface: Shared_PortType.java

generated service interface

_Service

XML: <wsdl: service name="shared" ... >

Java: Shared_Service.java

exception class

_Exception

Java: Shared_Exception.java

Default Algorithms to Map Between Target WSDL Namespaces and Java Package Names

The following sections describe the default algorithms that WebServicesAssembler uses to map between namespaces and package names.

Java Package Name to WSDL Namespace Mapping Algorithm

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 (http://www.iso.org/iso/en/ISOOnline.frontpage).

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.

Mapping Java Artifacts to WSDL Artifacts

The following steps represent the order in which the WebServicesAssembler tool attempts to map Java artifacts to WSDL artifacts.

  1. 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.

  2. Look up the value of the Java <package-mapping> element in the JAX-RPC mapping file.

  3. Derive the name of the WSDL namespace from the Java package name of the service endpoint interface.

Mapping Java Types to XML Schema Types

The following steps represent the order in which the WebServicesAssembler tool attempts to map Java types to XML schema types.

  1. Look up the value of the Java <package-mapping> element in the JAX-RPC mapping file.

  2. 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.

  3. Derive the WSDL namespace from the Java package of the value type.

  4. Use the value of the targetNamespace attribute defined in the WSDL.

WSDL Namespace to Java Package Name Mapping Algorithm

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 uxxxx, 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.

Mapping the WSDL Service Endpoint Interface and Related Endpoint Artifacts to Java Package and Class Names

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.

  1. 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.

  2. 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.

  3. Look up the value of the <package-mapping> element in the JAX-RPC mapping file.

  4. Derive the Java package name from WSDL namespace.

Mapping WSDL Value Types and Related Artifacts to Java Names and Types

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.

  1. 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.

  2. 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.

  3. Look up the value of the Java <package-mapping> element in the JAX-RPC mapping file.

  4. 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.

How to Specify a Namespace

Use the typeNamespace argument to explicitly specify a namespace. The name that you specify will always be used and it will not be reversed.

How to Specify a Root Package Name

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.

How to Establish a Database Connection

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.

Additional Ant Support for WebServicesAssembler

This section describes additional functionality that is available for WebServicesAssembler through Ant tasks. This functionality is not available on the WebServicesAssembler command line.

How to Use Multiple Instances of an Argument in Ant

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>

How to Configure Proxy Generation in an Ant Task

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>

How to Generate Handler and Port Information into a Proxy

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.

How to Configure a Port in an Ant Task

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").

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:

Example 18-7 Assigning Different SOAP Message Versions to Different Ports

<oracle:assemble 
   ...
      <oracle:port uri="soap11" soapVersion="1.1" name="httpSoap11Port" />
      <oracle:port uri="soap12" soapVersion="1.2" name="httpSoap12Port" />
   ...
/>

How to Configure a Port Type in an Ant Task

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.

See Also:

"How to Configure a Port in an Ant Task" for more information on port tags.

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

classFileName attribute

This attribute can be specified for the assemble and topDownAssemble commands if a className is not specified. It identifies the Java file name of the implementation class specified in the className argument.

className attribute

This attribute is required for the assemble, topDownAssemble, genDDs, and genWsdl commands. It specifies the name of the class (including the package name) that is the implementation class for the Web service.

interfaceName attribute

An interfaceName attribute is required. It identifies the interface to the Web service.

<port> subtag

A <port> subtag is required if you are specifying multiple <porttype> tags. It identifies the port to which the Web service interface applies. If you are specifying only one <porttype> tag, then a <port> tag is not required.

Example 18-8 illustrates assigning a port type to a Web service.

Example 18-8 Associating a Port Type to a Web Service

...
<oracle:porttype 
   interfaceName="my.company.MyInterface"   
   className="my.company.MyImpl">
</oracle:porttype>
...

How to Configure Handlers in an Ant Task

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.

Attributes and Child Tags for handler Tags

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> 
...

Sample Handler Configuration

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>

Ant Tasks that Can Configure Handlers

The Ant tasks for the following WebServiceAssembler commands allow you to specify a handler tag as a child task.

Configuring Multiple Handlers in an Ant Task

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>

How to Add Files to an Archive

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" 
                ...
 />

How to Control a WebServicesAssembler 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"
          ...
/>

How to Assemble Support for MTOM Encoded Attachemnts into a Web Service

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 mtomSupport attribute and how to use it, see the following sections:

  • "mtomSupport"

  • "Working wih MTOM Enoded Attachments" in the Oracle Application Server Advanced Web Services Developer's Guide

How to Assign Multiple Web Services to an EAR or WAR Archive

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.

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 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 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" 
              ... 
            />

Limitations on Assigning Multiple Web Services to a WAR File

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.

How to Represent Java Method Parameter Names in the WSDL

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.

  1. 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.

  2. 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>
...

Limitations

See "Using WebServicesAssembler".

Additional Information

For more information on:

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us