Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Web Services

# Using the WebLogic Web Services APIs

The following sections provide information about using the WebLogic Web Services APIs:

- Overview of the WebLogic Web Service APIs
- Registering Data Type Mapping Information in a Dynamic Client
- Accessing HttpSession Information from a Web Service Component
- Introspecting the WSDL from a Client Application

# Overview of the WebLogic Web Service APIs

WebLogic Web Services provide APIs, in addition to the JAX-RPC and SAAJ APIs, that you can use for a variety of tasks. These APIs are mostly for use in client applications, although in some cases you can use the APIs in server-side components, such as EJBs.

The sections here discuss the main usage scenarios for WebLogic Web Services APIs; for full reference information about the APIs, see the Javadocs.

The following table lists all the WebLogic Web Services APIs and their main uses.

Table 8-1 WebLogic Web Service APIs

Package Name | Typical Use Cases
--- | ---
`weblogic.webservice.async` | Used in a client application to invoke an operation asynchronously by splitting the invocation into two methods: the first method invokes the operation with the required parameters but does not wait for the result; later, the second method returns the actual results. See Writing an Asynchronous Client Application.
`weblogic.webservice.binding` | Used in a client application to set verbose mode and the character set programmatically. See Setting Verbose Mode Programatically and Setting the Character Set When Invoking a Web Service.
`weblogic.webservice.client` | Used in a client application to configure SSL. See Configuring SSL for a Client Application.
`weblogic.webservice.context` | Used to access the `HttpSession` information from within the implementation of a WebLogic Web Service operation. See Accessing HttpSession Information from a Web Service Component.
`weblogic.webservice.encoding` | Used in a dynamic client application to register data type mapping information about any non-built-in data types used as a parameter or return value in a Web Service operation invocation. See Registering Data Type Mapping Information in a Dynamic Client.
`weblogic.webservice.extensions` | Used in a client application to introspect the WSDL of the invoked Web Service. See Introspecting the WSDL from a Client Application.

# Registering Data Type Mapping Information in a Dynamic Client

The stubs in the client JAR file generated by the `clientgen` Ant task include the Java code needed by client applications to handle the data type mapping and registration for non-built-in data types used as parameters or return values of Web Service operations. If, however, you are writing a dynamic client to invoke the Web Service, then you must handle the data type mapping registration yourself because dynamic clients do not use the `clientgen`-generated stubs.

The standard way to register a data type mapping is to use the JAX-RPC `TypeMappingRegistry` class. However, using this class can be cumbersome because you must register the serialization classes manually, and some of these serialization classes might be internal WebLogic classes. The following example shows how to use the `TypeMappingRegistry` class, with the relevant code in bold:

>     package examples.jaxrpc.call3;

>     import javax.xml.soap.SOAPConstants;
>     import javax.xml.rpc.ServiceFactory;
>     import javax.xml.rpc.Service;
>     import javax.xml.rpc.Call;
>     import javax.xml.rpc.ParameterMode;

>     import javax.xml.namespace.QName;

>     import javax.xml.rpc.encoding.TypeMapping;
>     import javax.xml.rpc.encoding.TypeMappingRegistry;

>     import org.soapinterop.xsd.SOAPStructCodec;
>     import org.soapinterop.xsd.SOAPStruct;

>     public class MSInterop{

>     public static void main( String[] args ) throws Exception{

>         //set weblogic ServiceFactory
>         System.setProperty( "javax.xml.rpc.ServiceFactory",
>             "weblogic.webservice.core.rpc.ServiceFactoryImpl" );

>         //create service factory
>         ServiceFactory factory = ServiceFactory.newInstance();

>         //define qnames
>         String targetNamespace = "http://soapinterop.org/";

>         QName serviceName = new QName( targetNamespace, "SimpleTest" );
>         QName portName = new QName( targetNamespace, "SimpleTestSoap" );

>         QName operationName = new QName( "http://soapinterop.org/",
>             "echoStruct" );

>         //create service
>         Service service = factory.createService( serviceName );

>         TypeMappingRegistry registry = service.getTypeMappingRegistry();

>         TypeMapping mapping = registry.getTypeMapping(
>             SOAPConstants.URI_NS_SOAP_ENCODING );

>         mapping.register( SOAPStruct.class,
>             new QName( "http://soapinterop.org/xsd", "SOAPStruct" ),
>             new SOAPStructCodec(),
>             new SOAPStructCodec() );

>         //create call
>         Call call = service.createCall();

>         //set port and operation name
>         call.setPortTypeName( portName );
>         call.setOperationName( operationName );

>         call.addParameter( "inputStruct",
>             new QName( "http://soapinterop.org/xsd", "SOAPStruct" ),
>             ParameterMode.IN);

>         call.setReturnType(
>             new QName( "http://soapinterop.org/xsd", "SOAPStruct" ) );

>         //set end point address
>         call.setTargetEndpointAddress(
>             "http://www.mssoapinterop.org/asmx/simple.asmx" );

>         SOAPStruct s = new SOAPStruct();
>         s.setVarInt(2);
>         s.setVarString("foo");
>         s.setVarFloat(123123);
>         System.out.println(s.toString());

>         SOAPStruct res = (SOAPStruct) call.invoke(new Object[]{s} );

>         System.out.println( res );
>       }

>     }

The WebLogic Web Services weblogic.webservice.encoding package facilitates the mapping registration of non-built-in data types in a dynamic client. The API defines the following two main classes:

- `DefaultTypeMapping`: Used to register XML data types and associate them with a corresponding Java data type.
- `GenericTypeMapping`: Used to associate all non-built-in XML data types to the generic Java data type `SOAPElement`

The following procedure describes how to use the `DefaultTypeMapping` class in your dynamic client application:

1. Execute the `autotype` Ant task to create the serialization class, Java class, XML Schema, and `types.xml` file for the non-built-in data types used in your Web Service. Assume for this example that the `types.xml` file is generated in the `mydir` directory.

For details, see Running the autotype Ant Task.

2. In your client application, import the needed WebLogic Web Service API packages:

>     import weblogic.webservice.encoding.GenericTypeMapping;
>     import weblogic.webservice.encoding.DefaultTypeMapping;

3. Create an instance of the JAX-RPC `TypeMappingRegistry` object:

>     TypeMappingRegistry registry = service.getTypeMappingRegistry();

4. Use the `DefaultTypeMapping` class to register the `types.xml` file generated by the `autotype` Ant task, as shown in the following code excerpt:

>        registry.registerDefault(
>            new DefaultTypeMapping( "mydir/types.xml" ) );

# Accessing HttpSession Information from a Web Service Component

Use the weblogic.webservice.context.WebServiceSession class to access the infrastructure inside WebLogic Server that manages HTTP Sessions. Because WebLogic Web Services are not implemented with servlets, but rather with Java classes and EJBs, the HTTP session information is not directly available, so use the `weblogic.webservice.context` package to access it. See the Javadoc for javax.servlet.http.HttpSession for information on using `WebServiceSession`.

In your Web Service implementation, get a `WebServiceSession` object from a `WebServiceContext` object, and then use the standard `getAttribute()` and `setAttribute()` methods to get and set attributes of the session.

Note: In order for the session functionality to work, the client application must support HTTP cookies.

The following example shows a method of the Java class that implements a Web Service that uses the `weblogic.webservice.context` API. The method maintains session state between multiple invokes of the Web Service operation.

>     import weblogic.webservice.context.WebServiceContext;
>     import weblogic.webservice.context.ContextNotFoundException;
>     import weblogic.webservice.context.WebServiceSession;

>     ....

>      /*
>        * Shows how to use HTTP Session to maintain session state between
>        * invokes
>        */
>       public int maintainSessionState(){
>         try{
>           WebServiceContext wsContext = WebServiceContext.currentContext();
>           WebServiceSession session = (WebServiceSession)wsContext.getSession();

>           Integer count = (Integer)session.getAttribute( "count" );

>           count = (count==null) ?
>             new Integer( 0 ) : new Integer( count.intValue() + 1 );

>           session.setAttribute( "count", count );
>           return count.intValue();
>         }catch( ContextNotFoundException e ){
>           e.printStackTrace();
>           return -1;
>         }
>       }

# Introspecting the WSDL from a Client Application

Use the weblogic.webservice.extensions package in a dynamic client application to introspect the WSDL of the Web Service you are invoking. In particular, the `WLCall` interface extends the `javax.xml.rpc.Call` interface, adding functionality to:

- Get the names of all parameters of the operation you are invoking
- Get the Java data type of a particular parameter
- Get the mode of the parameter (in, out, in-out)

The following example shows how to use the `weblogic.webservice.extensions.WLCall` interface to get more information about the parameters of the operation you are invoking in a client application.

>     import java.io.IOException;

>     import java.net.URL;

>     import java.util.Iterator;

>     import java.rmi.RemoteException;

>     import javax.xml.namespace.QName;

>     import javax.xml.rpc.Service;
>     import javax.xml.rpc.ServiceFactory;
>     import javax.xml.rpc.ServiceException;
>     import javax.xml.rpc.Call;

>     import javax.xml.rpc.encoding.TypeMapping;
>     import javax.xml.rpc.encoding.TypeMappingRegistry;

>     import weblogic.webservice.encoding.GenericTypeMapping;
>     import weblogic.webservice.extensions.WLCall;

>     public class BrowserClient{

>       public void invoke() throws RemoteException, InvokeFailedException,
>         ServiceException, IOException{

>         String url = "http://localhost:7001/mega/TemperatureService?WSDL";

>         System.setProperty( "javax.xml.rpc.ServiceFactory",
>             "weblogic.webservice.core.rpc.ServiceFactoryImpl" );

>         System.setProperty( "weblogic.webservice.servicenamechecking",
>             "false" );

>         ServiceFactory factory = ServiceFactory.newInstance();

>         QName serviceName = new QName( "http://www.bea.com/mega-service/",
>             "MegaWebService" );

>         Service service = factory.createService( new URL( url ), serviceName );

>         TypeMappingRegistry registry = service.getTypeMappingRegistry();
>         registry.registerDefault( new GenericTypeMapping() );

>         System.out.println( "+ Service: " + service.getServiceName() );

>         for( Iterator it = service.getPorts(); it.hasNext(); ){
>           QName portName = (QName)it.next();
>           System.out.println( "  + Port: " + portName );
>           Call[] calls = service.getCalls( portName );
>           printCalls( calls );
>         }
>       }

>       private void printCalls( Call[] calls ){
>         for( int i=0; i<calls.length; i++ ){
>           Call call = calls[i];
>           System.out.println( "    + Operation :" + call.getOperationName() );
>           printParameters( (WLCall)call );

>           if( call.getReturnType() != null ){
>             System.out.println( "      + Return Type:" + call.getReturnType() );
>           }

>           System.out.println( "" );
>         }
>       }

>       private void printParameters( WLCall call ){
>         for( Iterator it = call.getParameterNames(); it.hasNext(); ){
>           String name = (String)it.next();
>           System.out.println( "      + Part :" + name );

>           System.out.println( "        - Java Type :" +
>               call.getParameterJavaType( name ) );

>           System.out.println( "        - Mode :" +
>               call.getParameterMode( name ) );

>           System.out.println( "        - XML Type :" +
>               call.getParameterTypeByName( name ) );
>         }
>       }
>     }