3 JWS Annotation Reference

The WebLogic web services programming model uses the JDK 5.0 metadata annotations feature, specified by JSR-175: A Metadata Facility for the JavaTM Programming Language, to provide a set of WebLogic-specific JWS annotations.

Overview of JWS Annotation Tags

In the metadata annotations programming model, you create an annotated Java file and then use Ant tasks to compile the file into the Java source code and generate all the associated artifacts.

The Java Web Service (JWS) annotated file is the core of your Web Service. It contains the Java code that determines how your Web Service behaves. A JWS file is an ordinary Java class file that uses annotations to specify the shape and characteristics of the Web Service.

The JWS annotations that are supported vary based on whether you are creating a JAX-WS or JAX-RPC Web Service. The following table compares the Web Service annotation support for JAX-WS and JAX-RPC.

You can target a JWS annotation at either the class-, method- or parameter-level in a JWS file. Some annotations can be targeted at more than one level, such as @SecurityRoles that can be targeted at both the class and method level.

The following example shows a simple JWS file that uses standard JSR-181, shown in bold:

package examples.webservices.complex;
// Import the standard JWS annotation interfaces
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
// Import the BasicStruct JavaBean
import examples.webservices.complex.BasicStruct;
// Standard JWS annotation that specifies that the portType name of the Web
// Service is "ComplexPortType", its public service name is "ComplexService",
// and the targetNamespace used in the generated WSDL is "http://example.org"
@WebService(serviceName="ComplexService", name="ComplexPortType",
            targetNamespace="http://example.org")
// Standard JWS annotation that specifies this is a document-literal-wrapped
// Web Service
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
             use=SOAPBinding.Use.LITERAL,
             parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
/**
 * This JWS file forms the basis of a WebLogic Web Service.  The Web Services
 * has two public operations:
 *
 *  - echoInt(int)
 *  - echoComplexType(BasicStruct)
 *
 * The Web Service is defined as a "document-literal" service, which means
 * that the SOAP messages have a single part referencing an XML Schema element
 * that defines the entire body.
 *
*/
public class ComplexImpl {
  // Standard JWS annotation that specifies that the method should be exposed
  // as a public operation.  Because the annotation does not include the
  // member-value "operationName", the public name of the operation is the
  // same as the method name: echoInt.
  //
  // The WebResult annotation specifies that the name of the result of the
  // operation in the generated WSDL is "IntegerOutput", rather than the
  // default name "return".   The WebParam annotation specifies that the input
  // parameter name in the WSDL file is "IntegerInput" rather than the Java
  // name of the parameter, "input".
  @WebMethod()
  @WebResult(name="IntegerOutput",
             targetNamespace="http://example.org/complex")
  public int echoInt(
      @WebParam(name="IntegerInput",
                targetNamespace="http://example.org/complex")
      int input)
  {
    System.out.println("echoInt '" + input + "' to you too!");
    return input;
  }
  // Standard JWS annotation to expose method "echoStruct" as a public operation
  // called "echoComplexType"
  // The WebResult annotation specifies that the name of the result of the
  // operation in the generated WSDL is "EchoStructReturnMessage",
  // rather than the default name "return".
  @WebMethod(operationName="echoComplexType")
  @WebResult(name="EchoStructReturnMessage",
             targetNamespace="http://example.org/complex")
  public BasicStruct echoStruct(BasicStruct struct)
  {
    System.out.println("echoComplexType called");
    return struct;
  }
}

The following sections describe the JWS annotations that are supported.

Web Services Metadata Annotations (JSR-181)

You can use standard JSR-181 annotations in your JWS file to specify the shape and behavior of your web service. The following table lists these annotations, which are available with the javax.jws at http://docs.oracle.com/javaee/7/api/javax/jws/package-summary.html or javax.jws.soap package at http://docs.oracle.com/javaee/7/api/javax/jws/soap/package-summary.html and are described in more detail in the Web Services Metadata for the Java Platform (JSR-181) specification at http://www.jcp.org/en/jsr/detail?id=181.

Table 3-2 Standard JSR-181 JWS Annotations

This annotation . . . Specifies . . .

javax.jws.WebService

At the class level that the JWS file implements a Web Service. For more information, see Specifying that the JWS File Implements a Web Service (@WebService Annotation) in Developing JAX-WS Web Services for Oracle WebLogic Server or in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server.

javax.jws.WebMethod

That a method of the JWS file should be exposed as a public operation of the Web Service. For more information, see Specifying That a JWS Method Be Exposed as a Public Operation (@WebMethod and @OneWay Annotations) in Developing JAX-WS Web Services for Oracle WebLogic Server or Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server.

javax.jws.OneWay

That an operation not return a value to the calling application. For more information, see Specifying That a JWS Method Be Exposed as a Public Operation (@WebMethod and @OneWay Annotations) in Developing JAX-WS Web Services for Oracle WebLogic Server or Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server.

javax.jws.WebParam

The mapping between operation input parameters of the Web Service and elements of the generated WSDL file, as well as specify the behavior of the parameter. For more information, see Customizing the Mapping Between Operation Parameters and WSDL Elements (@WebParam Annotation) in Developing JAX-WS Web Services for Oracle WebLogic Server or Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server.

javax.jws.WebResult

The mapping between the Web Service operation return value and the corresponding element of the generated WSDL file. For more information, see Customizing the Mapping Between the Operation Return Value and a WSDL Element (@WebResult Annotation) in Developing JAX-WS Web Services for Oracle WebLogic Server or Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server.

javax.jws.HandlerChain

An external handler chain. For more information, see Creating and Using SOAP Message Handlers in Developing JAX-WS Web Services for Oracle WebLogic Server or Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server.

javax.jws.SOAPBinding

At the class level the SOAP bindings of the Web Service (such as, document-encoded or document-literal-wrapped). For more information, see Specifying the Mapping of the Web Service to the SOAP Message Protocol (@SOAPBinding Annotation) in Developing JAX-WS Web Services for Oracle WebLogic Server or Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server.

JAX-WS Annotations (JSR-224)

You can use JAX-WS (JSR-224) annotations in your JWS file to specify the shape and behavior of your web service. The following table summarizes the ones that you can use, which are available with the javax.xml.ws package at http://docs.oracle.com/javaee/7/api/javax/xml/ws/package-summary.html and are described in more detail in JAX-WS 2.1 Annotations at http://jax-ws.java.net/nonav/2.1.4/docs/annotations.html.

Note:

The JAX-WS JWS annotations are relevant to JAX-WS web wervices only. This section does not apply to JAX-RPC web services.

Table 3-3 JAX-WS (JSR-244) Annotations

This annotation . . . Specifies . . .

javax.xml.ws.Action

Whether to allow an explicit association of a WS-Addressing Action message addressing property with input, output, and fault messages of the mapped WSDL operation.

javax.xml.ws.BindingType

The binding to use for a Web Service implementation class. See Specifying the Binding Type to Use for an Endpoint (@BindingType Annotation) in Developing JAX-WS Web Services for Oracle WebLogic Server.

javax.xml.ws.FaultAction

Whether to allow an explicit association of a WS-Addressing Action message addressing property with the fault messages of the WSDL operation mapped from the exception class. The @FaultAction annotation is used inside an @Action annotation.

javax.xml.ws.RequestWrapper

The request wrapper bean to be used at runtime for the methods in the endpoint interface.

javax.xml.ws.ResponseWrapper

The response wrapper bean to be used at runtime for the methods in the endpoint interface.

javax.xml.ws.ServiceMode

Whether a provider implementation works with the entire protocol message or with the payload only.

javax.xml.ws.WebEndpoint

The getPortName() methods of a generated service interface.

javax.xml.ws.WebFault

Service-specific exception classes to customize to the local and namespace name of the fault element and the name of the fault bean.

javax.xml.ws.WebServiceClient

A generated service interface.

javax.xml.ws.WebServiceProvider

A provider implementation class.

javax.xml.ws.WebServiceRef

A reference to a Web Service. See Defining a Web Service Reference Using the @WebServiceRef Annotation in Developing JAX-WS Web Services for Oracle WebLogic Server.

JAXB Annotations (JSR-222)

The JAXB (JSR-222) specification defines the JAXB annotations that you can use in your JWS file to specify the shape and behavior of your web service. The JAXB specification is available at http://jcp.org/en/jsr/detail?id=222, and the annotations you can use are summarized in the following table. Each of these annotations is available with the javax.xml.bind.annotation package at http://docs.oracle.com/javaee/7/api/javax/xml/bind/annotation/package-summary.html and are described in more detail in Customizing Java-to-XML Schema Mapping Using JAXB Annotations in Developing JAX-WS Web Services for Oracle WebLogic Server or the JAXB (JSR-222 at http://jcp.org/en/jsr/detail?id=222) specification.

Note:

The JAXB JWS annotations are relevant to JAX-WS Web Services only. This section does not apply to JAX-RPC Web Services.

Table 3-4 JAXB Mapping Annotations (JSR-222)

This annotation . . . Specifies . . .

javax.xml.bind.annotation.XmlAccessorType

Whether fields or properties are serialized by default. See Specifying Default Serialization of Fields and Properties (@XmlAccessorType) in Developing JAX-WS Web Services for Oracle WebLogic Server.

javax.xml.bind.annotation.XmlElement

That a property contained in a class be mapped to a local element in the XML schema complex type to which the containing class is mapped. See Mapping Properties to Local Elements (@XmlElement) in Developing JAX-WS Web Services for Oracle WebLogic Server.

javax.xml.bind.annotation.XmlRootElement

That a top-level class be mapped to a global element in the XML schema that is used by the WSDL of the Web Service. See Mapping a Top-level Class to a Global Element (@XmlRootElement) in Developing JAX-WS Web Services for Oracle WebLogic Server.

javax.xml.bind.annotation.XmlSeeAlso

The other classes to bind when binding the current class. See Binding a Set of Classes (@XmlSeeAlso) in Developing JAX-WS Web Services for Oracle WebLogic Server.

javax.xml.bind.annotation.XmlType

That a class or enum type be mapped to an XML Schema type. See Mapping a Value Class to a Schema Type (@XmlType) in Developing JAX-WS Web Services for Oracle WebLogic Server.

Common Annotations (JSR-250)

You can use JAX-WS (JSR-250) annotations in your JWS file to specify the shape and behavior of your web service. Each of these annotations are available with the javax.annotation package at http://docs.oracle.com/javaee/7/api/javax/annotation/package-summary.html and are described in more detail in the Common Annotations for the Java Platform (JSR-250) specification at http://jcp.org/en/jsr/detail?id=250.

Table 3-5 Common Annotations (JSR-250)

This annotation . . . Specifies . . .

javax.annotation.Resource

A resource that is needed by the application. This annotation may be applied to an application component class or to fields or methods of the component class.

javax.annotation.PostConstruct

A method that needs to be executed after dependency injection is done to perform initialization.

javax.annotation.PreDestroy

A callback notification om a method to signal that the instance is in the process of being removed by the container.

WebLogic-Specific Annotations

WebLogic web services define a set of JWS annotations that you can use to specify behavior and features in addition to the standard JSR-181 JWS annotations. The following table summarizes the WebLogic-specific annotations and whether they are supported for JAX-WS or JAX-RPC. (The majority of annotations are supported for JAX-RPC only.) Each annotation is described in more detail in the sections that follow.

Table 3-6 WebLogic-specific Annotations

This annotation . . . Specifies . . JAX-WS, JAX-RPC, or Both?

com.oracle.webservices.api.jms.JMSTransportClient

That the web service client supports SOAP over JMS transport connection protocol.

JAX-WS

com.oracle.webservices.api.jms.JMSTransportService

That the web service supports SOAP over JMS transport connection protocol.

JAX-WS

weblogic.jws.AsyncFailure

The method that handles a potential failure when the main JWS file invokes an operation of another Web Service asynchronously.

JAX-RPC

weblogic.jws.AsyncResponse

The method that handles the response when the main JWS file invokes an operation of another Web Service asynchronously.

JAX-RPC

weblogic.jws.Binding

Whether the Web Service uses version 1.1 or 1.2 of the Simple Object Access Protocol (SOAP) implementation when accepting or sending SOAP messages.

JAX-RPC

weblogic.jws.BufferQueue

The JNDI name of the JMS queue to which WebLogic Server stores:

  • Buffered Web Service operation invocation.

  • Reliable Web Service operation invocation.

JAX-RPC

weblogic.jws.Callback

That the annotated variable is a callback, which means that you can use the variable to send callback events back to the client Web Service that invoked an operation of the target Web Service.

JAX-RPC

weblogic.jws.CallbackMethod

The method in the client Web Service that handles the messages it receives from the callback Web Service.

JAX-RPC

weblogic.jws.CallbackService

That the JWS file is actually a Java interface that describes a callback Web Service.

JAX-RPC

weblogic.jws.Context

That the annotated field provides access to the runtime context of the Web Service.

JAX-RPC

weblogic.jws.Conversation

That a method annotated with the @Conversation annotation can be invoked as part of a conversation between two WebLogic Web Services or a stand-alone Java client and a conversational Web Service.

JAX-RPC

weblogic.jws.Conversational

That a JWS file implements a conversational Web Service.

JAX-RPC

weblogic.jws.FileStore

That the Web Service does not use the default WebLogic Server default filestore to store internal state information, such as conversational state, but rather uses one specified by the programmer.

JAX-RPC

weblogic.jws.MessageBuffer

Which public methods of a JWS are buffered. If specified at the class-level, then all public methods are buffered; if you want only a subset of the methods to be buffered, specify the annotation at the appropriate method-level.

JAX-RPC

weblogic.jws.Policies

An array of @weblogic.jws.Policy annotations.

Both

weblogic.jws.Policy

That a WS-Policy file, which contains information about digital signatures, encryption, or Web Service reliable messaging, should be applied to the request or response SOAP messages.

Both

weblogic.jws.ReliabilityBuffer

Reliable messaging properties for an operation of a reliable Web Service, such as the number of times WebLogic Server should attempt to deliver the message from the JMS queue to the Web Service implementation, and the amount of time that the server should wait in between retries.

JAX-RPC

weblogic.jws.ReliabilityErrorHandler

The method that handles the error that results when a client Web Service invokes a reliable Web Service, but the client does not receive an acknowledgement that the reliable Web Service actually received the message.

JAX-RPC

weblogic.jws.ServiceClient

That the annotated variable in the JWS file is a stub used to invoke another WebLogic Web Service when using the following features:

  • Web Service reliable messaging

  • Asynchronous request-response

  • Conversations

JAX-RPC

weblogic.jws.StreamAttachments

That the WebLogic Web Services runtime use streaming APIs when reading the parameters of all methods of the Web Service.

JAX-RPC

weblogic.jws.Transactional

Whether the annotated operation, or all the operations of the JWS file when the annotation is specified at the class-level, runs or run inside of a transaction.

JAX-RPC

weblogic.jws.Types

A comma-separated list of fully qualified Java class names of the alternative data types for a return type or parameter.

JAX-RPC

weblogic.jws.WildcardBinding

The XML Schema data type to which a wildcard class, such as javax.xml.soap.SOAPElement or org.apache.xmlbeans.XmlObject, binds.

JAX-RPC

weblogic.jws.WildcardBindings

An array of @weblogic.jws.WildcardBinding annotations.

JAX-RPC

weblogic.jws.WLHttpTransport (Deprecated)

The context path and service URI sections of the URL used to invoke the Web Service over the HTTP transport, as well as the name of the port in the generated WSDL.

JAX-RPC

weblogic.jws.WLHttpsTransport

The context path and service URI sections of the URL used to invoke the Web Service over the HTTPS transport, as well as the name of the port in the generated WSDL.

JAX-RPC

weblogic.jws.WLJmsTransport

The context path and service URI sections of the URL used to invoke the Web Service over the JMS transport, as well as the name of the port in the generated WSDL.

JAX-RPC

weblogic.jws.WSDL

Whether to expose the WSDL of a deployed WebLogic Web Service.

JAX-RPC

weblogic.jws.security.CallbackRolesAllowed

An array of @SecurityRole JWS annotations that list the roles that are allowed to invoke the callback methods of the Web Service.

JAX-RPC

we3blogic.jws.security.RolesAllowed

Whether to enable basic authentication for a Web Service.

JAX-RPC

weblogic.jws.security.RolesReferenced

The list of role names that reference actual roles that are allowed to invoke the Web Service.

JAX-RPC

weblogic.jws.security.RunAs

The role and user identity which actually runs the Web Service in WebLogic Server.

JAX-RPC

weblogic.jws.security.SecurityRole

The name of a role that is allowed to invoke the Web Service.

JAX-RPC

weblogic.jws.security.SecurityRoleRef

A role name reference that links to an already-specified role that is allowed to invoke the Web Service.

JAX-RPC

weblogic.jws.security.UserDataConstraint

Whether the client is required to use the HTTPS transport when invoking the Web Service.

JAX-RPC

weblogic.jws.security.WssConfiguration

The name of the Web Service security configuration you want the Web Service to use.

Both

weblogic.jws.soap.SOAPBinding

The mapping of a Web Service operation onto the SOAP message protocol.

JAX-RPC

weblogic.jws.security.SecurityRoles (deprecated)

The roles that are allowed to access the operations of the Web Service.

JAX-RPC

weblogic.jws.security.SecurityIdentity (deprecated)

The identity assumed by the Web Service when it is invoked.

JAX-RPC

weblogic.wsee.jws.jaxws.owsm.Property

A policy configuration property override.

Use this annotation with the weblogic.wsee.jws.jaxws.owsm.SecurityPolicy annotation to override a configuration property when attaching a policy to a web service client.

JAX-WS

weblogic.wsee.jws.jaxws.owsm.SecurityPolicies

An array of @weblogic.wsee.jws.jaxws.owsm.SecurityPolicies annotations.

JAX-WS

weblogic.wsee.jws.jaxws.owsm.SecurityPolicy

That an Oracle Web Services Manager (OWSM) security policy be attached to the web service or client.

JAX-WS

weblogic.wsee.jws.jaxws.owsm.SecurityPolicies

An array of @weblogic.jws.SecurityPolicy annotations.

JAX-WS

weblogic.wsee.jws.jaxws.owsm.SecurityPolicy

That an Oracle Web Services Manager (Oracle WSM) WS-Policy file, which contains information about digital signatures or encryption, should be applied to the request or response SOAP messages.

JAX-WS

weblogic.wsee.wstx.wsat.Transactional

Whether the annotated class or method runs inside of a web service atomic transaction.

JAX-WS

com.oracle.webservices.api.jms.JMSTransportClient

Target: Class

Enables and configures SOAP over JMS transport for JAX-WS web service clients.

Using SOAP over JMS transport, web services and clients communicate using JMS destinations instead of HTTP connections, offering the following benefits:

  • Reliability

  • Scalability

  • Quality of service

For more information about using SOAP over JMS transport, see Using SOAP Over JMS Transport as the Connection Protocol in Developing JAX-WS Web Services for Oracle WebLogic Server.

Attributes

Optionally, you can configure the following JMS transport properties using the @JMSTransportClient annotation. For a description of the properties, see Configuring JMS Transport Properties in Developing JAX-WS Web Services for Oracle WebLogic Server.

  • destinationName

  • destinationType

  • enabled

  • jmsHeaderProperty

  • jmsMessageProperty

  • jndiConnectionFactoryName

  • jndiContextParameters

  • jndiInitialContextFactory

  • jndiURL

  • messageType

  • priority

  • replyToName

  • targetService

  • timeToLive

Note:

You cannot use SOAP over JMS transport in conjunction with web services reliable messaging or streaming SOAP attachments, as described in Developing JAX-WS Web Services for Oracle WebLogic Server.

Example

The following sample snippet shows how to use the @JMSTransportClient annotation in a client file to enable SOAP over JMS transport.

...
import javax.xml.ws.WebServiceClient;
import com.oracle.webservices.api.jms.JMSTransportClient;
...
@WebServiceClient(name = "WarehouseService", targetNamespace = "http://oracle.com/samples/", 
                  wsdlLocation="WarehouseService.wsdl")
@JMSTransportClient (
    destinationName="myQueue", 
    replyToName="myReplyToQueue",
    jndiURL="t3://localhost:7001",
    jndiInitialContextFactory="weblogic.jndi.WLInitialContextFactory" , 
    jndiConnectionFactoryName="weblogic.jms.ConnectionFactory" , 
    deliveryMode="PERSISTENT", timeToLive="1000", priority="1", 
    messageType="TEXT" 
)

public class WarehouseService  extends Service { ... }

com.oracle.webservices.api.jms.JMSTransportService

Target: Class

Enables and configures SOAP over JMS transport for JAX-WS web services.

Using SOAP over JMS transport, web services and clients communicate using JMS destinations instead of HTTP connections, offering the following benefits:

  • Reliability

  • Scalability

  • Quality of service

For more information about using SOAP over JMS transport, see Using SOAP Over JMS Transport as the Connection Protocol in Developing JAX-WS Web Services for Oracle WebLogic Server.

Note:

SOAP over JMS transport is not compatible with the following web service features: reliable messaging and HTTP transport-specific security.

Attributes

Optionally, you can configure JMS transport properties using the @JMSTransportService annotation. For a description of the properties, see Configuring JMS Transport Properties in Developing JAX-WS Web Services for Oracle WebLogic Server.

Example

The following sample snippet shows how to use the @JMSTransportService annotation in a JWS file to enable SOAP over JMS transport. The @ActivationConfigProperty is used to set service-side MDB configuration properties.

import javax.jws.WebService;
import com.oracle.webservices.api.jms.JMSTransportService;
import com.sun.xml.ws.binding.SOAPBindingImpl;
import javax.ejb.ActivationConfigProperty;
@WebService(name="NotifyServicePortType", serviceName="NotifyService", 
   targetNamespace="http://examples.org/")
@JMSTransportService(destinationName="myQueue", 
   activationConfig = { 
      @ActivationConfigProperty(
         propertyName  = "destinationType", 
         propertyValue = "javax.jms.Topic"),
      @ActivationConfigProperty(
         propertyName  = "subscriptionDurability",
         propertyValue = "Durable"),
      @ActivationConfigProperty(propertyName  = "topicMessagesDistributionMode",
         propertyValue = "One-Copy-Per-Application")})
@BindingType(SOAPBindingImpl.SOAP11_JMS_BINDING)
public class NotifyServiceImpl {..}

weblogic.jws.AsyncFailure

Target: Method

Specifies the method that handles a potential failure when the main JWS file invokes an operation of another Web Service asynchronously.

When you invoke, from within a JWS file, a Web Service operation asynchronously, the response (or exception, in the case of a failure) does not return immediately after the operation invocation, but rather, at some later point in time. Because the operation invocation did not wait for a response, a separate method in the JWS file must handle the response when it does finally return; similarly, another method must handle a potential failure. Use the @AsyncFailure annotation to specify the method in the JWS file that will handle the potential failure of an asynchronous operation invocation.

The @AsyncFailure annotation takes two parameters: the name of the stub for the Web Service you are invoking and the name of the operation that you are invoking asynchronously. The stub is the one that has been annotation with the @ServiceClient annotation.

The method that handles the asynchronous failure must follow these guidelines:

  • Return void.

  • Be named onMethodNameAsyncFailure, where MethodName is the name of the method you are invoking asynchronously (with initial letter always capitalized.)

    In the main JWS file, the call to the asynchronous method will look something like:

    port.getQuoteAsync (apc, symbol);
    

    where getQuote is the non-asynchronous name of the method, apc is the asynchronous pre-call context, and symbol is the usual parameter to the getQuote operation.

  • Have two parameters: the asynchronous post-call context (contained in the weblogic.wsee.async.AsyncPostCallContext object) and the Throwable exception, potentially thrown by the asynchronous operation call.

Within the method itself you can get more information about the method failure from the context, and query the specific type of exception and act accordingly.

Typically, you always use the @AsyncFailure annotation to explicitly specify the method that handles asynchronous operation failures. The only time you would not use this annotation is if you want a single method to handle failures for two or more stubs that invoke different Web Services. In this case, although the stubs connect to different Web Services, each Web Service must have a similarly named method, because the Web Services runtime relies on the name of the method (onMethodNameAsyncFailure) to determine how to handle the asynchronous failure, rather than the annotation. However, if you always want a one-to-one correspondence between a stub and the method that handles an asynchronous failure from one of the operations, then Oracle recommends that you explicitly use @AsyncFailure.

See Invoking a Web Service Using Asynchronous Request-Response in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for detailed information and examples of using this annotation.

Attributes

The following table lists the attributes of the @AsyncFailure annotation.

Table 3-7 Attributes of the weblogic.jws.AsyncFailure Annotation

Name Description Data Type Required?

target

The name of the stub of the Web Service for which you want to invoke an operation asynchronously.

The stub is the one that has been annotated with the @ServiceClient field-level annotation.

String

Yes

operation

The name of the operation that you want to invoke asynchronously.

This is the actual name of the operation, as it appears in the WSDL file. When you invoke this operation in the main code of the JWS file, you add Async to its name.

For example, if set operation="getQuote", then in the JWS file you invoke it asynchronously as follows:

port.getQuoteAsync (apc, symbol);

String

Yes

Example

The following sample snippet shows how to use the @AsyncFailure annotation in a JWS file that invokes the operation of another Web Service asynchronously; only the relevant Java code is included:

package examples.webservices.async_req_res;
...
public class StockQuoteClientImpl {
  @ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
                 serviceName="StockQuoteService", portName="StockQuote")
  private StockQuotePortType port;
  @WebMethodpublic void getQuote (String symbol) {
    AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
    apc.setProperty("symbol", symbol);
    try {
      port.getQuoteAsync(apc, symbol );
      System.out.println("in getQuote method of StockQuoteClient WS");
    }
    catch (RemoteException e) {
      e.printStackTrace();
    }
  }
...
  @AsyncFailure(target="port", operation="getQuote")
  public void onGetQuoteAsyncFailure(AsyncPostCallContext apc, Throwable e) {
    System.out.println("-------------------");
    e.printStackTrace();
    System.out.println("-------------------");
  }
}

The example shows a stub called port, used to invoke the Web Service located at http://localhost:7001/async/StockQuote. The getQuote operation is invoked asynchronously, and any exception from this invocation is handled by the onGetQuoteAsyncFailure method, as specified by the @AsyncFailure annotation.

weblogic.jws.AsyncResponse

Target: Method

Specifies the method that handles the response when the main JWS file invokes an operation of another Web Service asynchronously.

When you invoke, from within a JWS file, a Web Service operation asynchronously, the response does not return immediately after the operation invocation, but rather, at some later point in time. Because the operation invocation did not wait for a response, a separate method in the JWS file must handle the response when it does finally return. Use the @AsyncResponse annotation to specify the method in the JWS file that will handle the response of an asynchronous operation invocation.

The @AsyncResponse annotation takes two parameters: the name of the stub for the Web Service you are invoking and the name of the operation that you are invoking asynchronously. The stub is the one that has been annotation with the @ServiceClient annotation.

The method that handles the asynchronous response must follow these guidelines:

  • Return void.

  • Be named onMethodNameAsyncResponse, where MethodName is the name of the method you are invoking asynchronously (with initial letter always capitalized.)

    In the main JWS file, the call to the asynchronous method will look something like:

    port.getQuoteAsync (apc, symbol);
    

    where getQuote is the non-asynchronous name of the method, apc is the asynchronous pre-call context, and symbol is the usual parameter to the getQuote operation.

  • Have two parameters: the asynchronous post-call context (contained in the weblogic.wsee.async.AsyncPostCallContext object) and the usual return value of the operation.

Within the asynchronous-response method itself you add the code to handle the response. You can also get more information about the method invocation from the context.

Typically, you always use the @AsyncResponse annotation to explicitly specify the method that handles asynchronous operation responses. The only time you would not use this annotation is if you want a single method to handle the response for two or more stubs that invoke different Web Services. In this case, although the stubs connect to different Web Services, each Web Service must have a similarly named method, because the Web Services runtime relies on the name of the method (onMethodNameAsyncResponse) to determine how to handle the asynchronous response, rather than the annotation. However, if you always want a one-to-one correspondence between a stub and the method that handles an asynchronous response from one of the operations, then Oracle recommends that you explicitly use @AsyncResponse.

See Invoking a Web Service Using Asynchronous Request-Response in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for detailed information and examples of using this annotation.

Attributes

Table 3-8 Attributes of the weblogic.jws.AsyncResponse JWS Annotation Tag

Name Description Data Type Required?

target

The name of the stub of the Web Service for which you want to invoke an operation asynchronously.

The stub is the one that has been annotated with the @ServiceClient field-level annotation.

String

Yes

operation

The name of the operation that you want to invoke asynchronously.

This is the actual name of the operation, as it appears in the WSDL file. When you invoke this operation in the main code of the JWS file, you add Async to its name.

For example, if set operation="getQuote", then in the JWS file you invoke it asynchronously as follows:

port.getQuoteAsync (apc, symbol);

String

Yes

Example

The following sample snippet shows how to use the @AsyncResponse annotation in a JWS file that invokes the operation of another Web Service asynchronously; only the relevant Java code is included:

package examples.webservices.async_req_res;
...
public class StockQuoteClientImpl {
  @ServiceClient(wsdlLocation="http://localhost:7001/async/StockQuote?WSDL",
                 serviceName="StockQuoteService", portName="StockQuote")
  private StockQuotePortType port;
  @WebMethodpublic void getQuote (String symbol) {
    AsyncPreCallContext apc = AsyncCallContextFactory.getAsyncPreCallContext();
    apc.setProperty("symbol", symbol);
    try {
      port.getQuoteAsync(apc, symbol );
      System.out.println("in getQuote method of StockQuoteClient WS");
    }
    catch (RemoteException e) {
      e.printStackTrace();
    }
  }
...
  @AsyncResponse(target="port", operation="getQuote")
  public void onGetQuoteAsyncResponse(AsyncPostCallContext apc, int quote) {
    System.out.println("-------------------");
    System.out.println("Got quote " + quote );
    System.out.println("-------------------");
  }
}

The example shows a stub called port, used to invoke the Web Service located at http://localhost:7001/async/StockQuote. The getQuote operation is invoked asynchronously, and the response from this invocation is handled by the onGetQuoteAsyncResponse method, as specified by the @AsyncResponse annotation.

weblogic.jws.Binding

Target: Class

Specifies whether the Web Service uses version 1.1 or 1.2 of the Simple Object Access Protocol (SOAP) implementation when accepting or sending SOAP messages. By default, WebLogic Web Services use SOAP 1.1.

Attributes

Table 3-9 Attributes of the weblogic.jws.Binding JWS Annotation Tag

Name Description Data Type Required?

value

Specifies the version of SOAP used in the request and response SOAP messages when the Web Service is invoked.

Valid values for this attribute are:

  • Type.SOAP11

  • Type.SOAP12

The default value is Type.SOAP11.

enum

No

Example

The following example shows how to specify SOAP 1.2; only the relevant code is shown:

package examples.webservices.soap12;
...
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.Binding;
@WebService(name="SOAP12PortType",
            serviceName="SOAP12Service",
            targetNamespace="http://example.org")
@Binding(Binding.Type.SOAP12)
public class SOAP12Impl {
  @WebMethod()
  public String sayHello(String message) {
...
  }
}

weblogic.jws.BufferQueue

The following sections describe the annotation in detail.

Description

Target: Class

Specifies the JNDI name of the JMS queue to which WebLogic Server stores:

  • Buffered Web Service operation invocation.

  • Reliable Web Service operation invocation.

When used with buffered Web Services, you use this annotation in conjunction with @MessageBuffer, which specifies the methods of a JWS that are buffered. When used with reliable Web Services, you use this annotation in conjunction with @Policy, which specifies the reliable messaging WS-Policy file associated with the Web Service.

If you have enabled buffering or reliable messaging for a Web Service, but do not specify the @BuffereQueue annotation, WebLogic Server uses the default Web Services JMS queue (weblogic.wsee.DefaultQueue) to store buffered or reliable operation invocations. This JMS queue is also the default queue for the JMS transport features. It is assumed that you have already created this JMS queue if you intend on using it for any of these features.

See Creating Buffered Web Services and Using Web Services Reliable Messaging in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for detailed information and examples of creating buffered or reliable Web Services.

Attributes

Table 3-10 Attributes of the weblogic.jws.BufferQueue JWS Annotation Tag

Name Description Data Type Required?

name

The JNDI name of the JMS queue to which the buffered or reliable operation invocation is queued.

String

Yes

Example

The following example shows a code snippet from a JWS file in which the public operation is buffered and the JMS queue to which WebLogic Server queues the operation invocation is called my.buffere.queue; only the relevant Java code is shown:

package examples.webservices.buffered;
...
@WebService(name="BufferedPortType",
            serviceName="BufferedService",
            targetNamespace="http://example.org")
@BufferQueue(name="my.buffer.queue")
public class BufferedImpl {
...
  @WebMethod()
  @MessageBuffer(retryCount=10, retryDelay="10 seconds")
  @Oneway()
  public void sayHelloNoReturn(String message) {
    System.out.println("sayHelloNoReturn: " + message);
  }
}

weblogic.jws.Callback

The following sections describe the annotation in detail.

Description

Target: Field

Specifies that the annotated variable is a callback, which means that you can use the variable to send callback events back to the client Web Service that invoked an operation of the target Web Service.

You specify the @Callback annotation in the target Web Service so that it can call back to the client Web Service. The data type of the annotated variable is the callback interface.

The callback feature works between two WebLogic Web Services. When you program the feature, however, you create the following three Java files:

  • Callback interface: Java interface file that defines the callback methods. You do not explicitly implement this file yourself; rather, the jwsc Ant task automatically generates an implementation of the interface. The implementation simply passes a message from the target Web Service back to the client Web Service. The generated Web Service is deployed to the same WebLogic Server that hosts the client Web Service.

  • JWS file that implements the target Web Service: The target Web Service includes one or more standard operations that invoke a method defined in the callback interface; this method in turn sends a message back to the client Web Service that originally invoked the operation of the target Web Service.

  • JWS file that implements the client Web Service: The client Web Service invokes an operation of the target Web Service. This Web Service includes one or more methods that specify what the client should do when it receives a callback message back from the target Web Service via a callback method.

See Using Callbacks to Notify Clients of Events in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for additional overview and procedural information about programming callbacks.

The @Callback annotation does not have any attributes.

Example

The following example shows a very simple target Web Service in which a variable called callback is annotated with the @Callback annotation. The data type of the variable is CallbackInterface; this means a callback Web Service must exist with this name. After the variable is injected with the callback information, you can invoke the callback methods defined in CallbackInterface; in the example, the callback method is callbackOperation().

The text in bold shows the relevant code:

package examples.webservices.callback;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.Callback;
import javax.jws.WebService;
import javax.jws.WebMethod;
@WebService(name="CallbackPortType",
            serviceName="TargetService",
            targetNamespace="http://examples.org/")
@WLHttpTransport(contextPath="callback",
                 serviceUri="TargetService",
                 portName="TargetServicePort")
public class TargetServiceImpl {
  @Callback
  CallbackInterface callback;
  @WebMethod
  public void targetOperation (String message) {
        callback.callbackOperation (message);
  }
}

weblogic.jws.CallbackMethod

The following sections describe the annotation in detail.

Description

Target: Method

Specifies the method in the client Web Service that handles the messages it receives from the callback Web Service. Use the attributes to link the callback message handler methods in the client Web Service with the callback method in the callback interface.

The callback feature works between two WebLogic Web Services. When you program the feature, however, you create the following three Java files:

  • Callback interface: Java interface file that defines the callback methods. You do not explicitly implement this file yourself; rather, the jwsc Ant task automatically generates an implementation of the interface. The implementation simply passes a message from the target Web Service back to the client Web Service. The generated Web Service is deployed to the same WebLogic Server that hosts the client Web Service.

  • JWS file that implements the target Web Service: The target Web Service includes one or more standard operations that invoke a method defined in the callback interface; this method in turn sends a message back to the client Web Service that originally invoked the operation of the target Web Service.

  • JWS file that implements the client Web Service: The client Web Service invokes an operation of the target Web Service. This Web Service includes one or more methods that specify what the client should do when it receives a callback message back from the target Web Service via a callback method.

See Using Callbacks to Notify Clients of Events in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for additional overview and procedural information about programming callbacks.

Attributes

Table 3-11 Attributes of the weblogic.jws.CallbackMethod JWS Annotation Tag

Name Description Data Type Required?

operation

Specifies the name of the callback method in the callback interface for which this method will handle callback messages.

String

Yes

target

Specifies the name of the stub for which you want to receive callbacks.

The stub is the one that has been annotated with the @ServiceClient field-level annotation.

String

Yes

Example

The following example shows a method of a client Web Service annotated with the @CallbackMethod annotation. The attributes show that a variable called port must have previously been injected with stub information and that the annotated method will handle messages received from a callback operation called callbackOperation().

  @CallbackMethod(target="port", operation="callbackOperation")
  @CallbackRolesAllowed(@SecurityRole(role="engineer",  mapToPrincipals="shackell"))
  public void callbackHandler(String msg) {
        System.out.println (msg);
  }

weblogic.jws.CallbackService

The following sections describe the annotation in detail.

Description

Target: Class

Specifies that the JWS file is actually a Java interface that describes a callback Web Service. This annotation is analogous to the @javax.jws.WebService, but specific to callbacks and with a reduced set of attributes.

The callback feature works between two WebLogic Web Services. When you program the feature, however, you create the following three Java files:

  • Callback interface: Java interface file that defines the callback methods. You do not explicitly implement this file yourself; rather, the jwsc Ant task automatically generates an implementation of the interface. The implementation simply passes a message from the target Web Service back to the client Web Service. The generated Web Service is deployed to the same WebLogic Server that hosts the client Web Service.

  • JWS file that implements the target Web Service: The target Web Service includes one or more standard operations that invoke a method defined in the callback interface; this method in turn sends a message back to the client Web Service that originally invoked the operation of the target Web Service.

  • JWS file that implements the client Web Service: The client Web Service invokes an operation of the target Web Service. This Web Service includes one or more methods that specify what the client should do when it receives a callback message back from the target Web Service via a callback method.

Use the @CallbackInterface annotation to specify that the Java file is a callback interface file.

When you program the callback interface, you specify one or more callback methods; as with standard non-callback Web Services, you annotate these methods with the @javax.jws.WebMethod annotation to specify that they are Web Service operations. However, contrary to non-callback methods, you never write the actual implementation code for these callback methods; rather, when you compile the client Web Service with the jwsc Ant task, the task automatically creates an implementation of the interface and packages it into a Web Service. This generated implementation specifies that the callback methods all do the same thing: send a message from the target Web Service that invokes the callback method back to the client Web Service.

See Using Callbacks to Notify Clients of Events in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for additional overview and procedural information about programming callbacks.

Attributes

Table 3-12 Attributes of the weblogic.jws.CallbackService JWS Annotation Tag

Name Description Data Type Required?

name

Name of the callback Web Service. Maps to the <wsdl:portType> element in the WSDL file.

Default value is the unqualified name of the Java class in the JWS file.

String

No

serviceName

Service name of the callback Web Service. Maps to the <wsdl:service> element in the WSDL file.

Default value is the unqualified name of the Java class in the JWS file, appended with the string Service.

String

No

Example

The following example shows a very simple callback interface. The resulting callback Web Service has one callback method, callbackOperation().

package examples.webservices.callback;
import weblogic.jws.CallbackService;
import javax.jws.Oneway;
import javax.jws.WebMethod;
@CallbackService
public interface CallbackInterface {
  @WebMethod
  @Oneway
  public void callbackOperation (String msg);
}

weblogic.jws.Context

The following sections describe the annotation in detail.

Description

Target: Field

Specifies that the annotated field provides access to the runtime context of the Web Service.

When a client application invokes a WebLogic Web Service that was implemented with a JWS file, WebLogic Server automatically creates a context that the Web Service can use to access, and sometimes change, runtime information about the service. Much of this information is related to conversations, such as whether the current conversation is finished, the current values of the conversational properties, changing conversational properties at runtime, and so on. Some of the information accessible via the context is more generic, such as the protocol that was used to invoke the Web Service (HTTP/S or JMS), the SOAP headers that were in the SOAP message request, and so on. The data type of the annotation field must be weblogic.wsee.jws.JwsContext, which is a WebLogic Web Service API that includes methods to query the context.

For additional information about using this annotation, see Accessing Runtime Information about a Web Service in Developing JAX-WS Web Services for Oracle WebLogic Server.

This annotation does not have any attributes.

Example

The following snippet of a JWS file shows how to use the @Context annotation; only parts of the file are shown, with relevant code in bold:

...
import weblogic.jws.Context;
import weblogic.wsee.jws.JwsContext;

...
public class JwsContextImpl {
  @Context
  private JwsContext ctx;
  @WebMethod()
  public String getProtocol() {
...

weblogic.jws.Conversation

Description

Target: Method

Specifies that a method annotated with the @Conversation annotation can be invoked as part of a conversation between two WebLogic Web Services or a stand-alone Java client and a conversational Web Service.

The conversational Web Service typically specifies three methods, each annotated with the @Conversation annotation that correspond to the start, continue, and finish phases of a conversation. Use the @Conversational annotation to specify, at the class level, that a Web Service is conversational and to configure properties of the conversation, such as the maximum idle time.

If the conversation is between two Web Services, the client service uses the @ServiceClient annotation to specify the wsdl, service name, and port of the invoked conversational service. In both the service and stand-alone client cases, the client then invokes the start, continue, and finish methods in the appropriate order to conduct a conversation.The only additional requirement to make a Web Service conversational is that it implement java.io.Serializable.

See Creating Conversational Web Services in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for detailed information and examples of using this annotation.

Attributes

Table 3-13 Attributes of the weblogic.jws.Conversation JWS Annotation Tag

Name Description Data Type Required?

value

Specifies the phase of a conversation that the annotated method implements.

Possible values are:

  • Phase.START

    Specifies that the method starts a new conversation. A call to this method creates a new conversation ID and context, and resets its idle and age timer.

  • Phase.CONTINUE

    Specifies that the method is part of a conversation in progress. A call to this method resets the idle timer. This method must always be called after the start method and before the finish method.

  • Phase.FINISH

    Specifies that the method explicitly finishes a conversation in progress.

Default value is Phase.CONTINUE

enum

No

Example

The following sample snippet shows a JWS file that contains three methods, start, middle, and finish) that are annotated with the @Conversation annotation to specify the start, continue, and finish phases, respectively, of a conversation.

...
public class ConversationalServiceImpl implements Serializable {
  @WebMethod
  @Conversation (Conversation.Phase.START)
  public String start() {
    // Java code for starting a conversation goes here
  }
  @WebMethod
  @Conversation (Conversation.Phase.CONTINUE)
  public String middle(String message) {
    // Java code for continuing a conversation goes here
  }
  @WebMethod
  @Conversation (Conversation.Phase.FINISH)
  public String finish(String message ) {
    // Java code for finishing a conversation goes here
  }
}

weblogic.jws.Conversational

The following sections describe the annotation in detail.

Description

Target: Class

Specifies that a JWS file implements a conversational Web Service.

You are not required to use this annotation to specify that a Web Service is conversational; by simply annotating a single method with the @Conversation annotation, all the methods of the JWS file are automatically tagged as conversational. Use the class-level @Conversational annotation only if you want to change some of the conversational behavior or if you want to clearly show at the class level that the JWS if conversational.

If you do use the @Conversational annotation in your JWS file, you can specify it without any attributes if their default values suit your needs. However, if you want to change values such as the maximum amount of time that a conversation can remain idle, the maximum age of a conversation, and so on, specify the appropriate attribute.

See Creating Conversational Web Services in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for detailed information and examples of using this annotation.

Attributes

Table 3-14 Attributes of the weblogic.jws.Conversational JWS Annotation Tag

Name Description Data Type Required?

maxIdleTime

Specifies the amount of time that a conversation can remain idle before it is finished by WebLogic Server. Activity is defined by a client Web Service executing one of the phases of the conversation.

Valid values are a number and one of the following terms:

  • seconds

  • minutes

  • hours

  • days

  • years

For example, to specify a maximum idle time of ten minutes, specify the annotation as follows:

@Conversational(maxIdleTime="10 minutes")

If you specify a zero-length value (such as 0 seconds, or 0 minutes and so on), then the conversation never times out due to inactivity.

Default value is 0 seconds.

String

No

maxAge

The amount of time that a conversation can remain active before it is finished by WebLogic Server.

Valid values are a number and one of the following terms:

  • seconds

  • minutes

  • hours

  • days

  • years

For example, to specify a maximum age of three days, specify the annotation as follows:

@Conversational(maxAge="3 days")

Default value is 1 day.

String

No

runAsStartUser

Specifies whether the continue and finish phases of an existing conversation are run as the user who started the conversation.

Typically, the same user executes the start, continue, and finish methods of a conversation, so that changing the value of this attribute has no effect. However, if you set the singlePrincipal attribute to false, which allows users different from the user who initiated the conversation to execute the continue and finish phases of an existing conversation, then the runAsStartUser attribute specifies which user the methods are actually "run as": the user who initiated the conversation or the different user who executes subsequent phases of the conversation.

Valid values are true and false. Default value is false.

boolean

No

singlePrincipal

Specifies whether users other than the one who started a conversation are allowed to execute the continue and finish phases of the conversation.

Typically, the same user executes all phases of a conversation. However, if you set this attribute to false, then other users can obtain the conversation ID of an existing conversation and use it to execute later phases of the conversation.

Valid values are true and false. Default value is false.

boolean

No

Example

The following sample snippet shows how to specify that a JWS file implements a conversational Web Service. The maximum amount of time the conversation can be idle is ten minutes, and the maximum age of the conversation, regardless of activity, is one day. The continue and finish phases of the conversation can be executed by a user other than the one that started the conversation; if this happens, then the corresponding methods are run as the new user, not the original user.

package examples.webservices.conversation;
...
@Conversational(maxIdleTime="10 minutes",
                maxAge="1 day",
                runAsStartUser=false,
                singlePrincipal=false )
public class ConversationalServiceImpl implements Serializable {
...

weblogic.jws.FileStore

The following sections describe the annotation in detail.

Description

Target: Class

Specifies that the Web Service does not use the default WebLogic Server default filestore to store internal state information, such as conversational state, but rather uses one specified by the programmer. If you do not specify this JWS annotation in your JWS file, the Web Service uses the default filestore configured for WebLogic Server.

You can also use this JWS annotation for reliable Web Services to store internal state.

If you deploy the Web Service in a cluster, be sure you specify the logical name of the filestore so that the same name of the filestore can be used on all servers in the cluster.

Note:

This annotation applies only to filestores, not to JDBC stores.

Attributes

Table 3-15 Attributes of the weblogic.jws.FileStore JWS Annotation Tag

Name Description Data Type Required?

storeName

Specifies the name of the filestore.

String

Yes

weblogic.jws.MessageBuffer

The following sections describe the annotation in detail.

Description

Target: Class, Method

Specifies which public methods of a JWS are buffered. If specified at the class-level, then all public methods are buffered; if you want only a subset of the methods to be buffered, specify the annotation at the appropriate method-level.

When a client Web Service invokes a buffered operation of a different WebLogic Web Service, WebLogic Server (hosting the invoked Web Service) puts the invoke message on a JMS queue and the actual invoke is dealt with later on when the WebLogic Server delivers the message from the top of the JMS queue to the Web Service implementation. The client does not need to wait for a response, but rather, continues on with its execution. For this reason, buffered operations (without any additional asynchronous features) can only return void and must be marked with the @Oneway annotation. If you want to buffer an operation that returns a value, you must use asynchronous request-response from the invoking client Web Service. See Invoking a Web Service Using Asynchronous Request-Response in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for more information.

Buffering works only between two Web Services in which one invokes the buffered operations of the other.

Use the optional attributes of @MessageBuffer to specify the number of times the JMS queue attempts to invoke the buffered Web Service operation until it is invoked successfully, and the amount of time between attempts.

Use the optional class-level @BufferQueue annotation to specify the JMS queue to which the invoke messages are queued. If you do not specify this annotation, the messages are queued to the default Web Service queue, weblogic.wsee.DefaultQueue.

See Creating Buffered Web Services in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for detailed information and examples for using this annotation.

Attributes

Table 3-16 Attributes of the weblogic.jws.MessageBuffer JWS Annotation Tag

Name Description Data Type Required?

retryCount

Specifies the number of times that the JMS queue on the invoked WebLogic Server instance attempts to deliver the invoking message to the Web Service implementation until the operation is successfully invoked.

Default value is 3.

int

No

retryDelay

Specifies the amount of time that elapses between message delivery retry attempts. The retry attempts are between the invoke message on the JMS queue and delivery of the message to the Web Service implementation.

Valid values are a number and one of the following terms:

  • seconds

  • minutes

  • hours

  • days

  • years

For example, to specify a retry delay of two days, specify:

@MessageBuffer(retryDelay="2 days")

Default value is 5 seconds.

String

No

Example

The following example shows a code snippet from a JWS file in which the public operation sayHelloNoReturn is buffered and the JMS queue to which WebLogic Server queues the operation invocation is called my.buffere.queue. The WebLogic Server instance that hosts the invoked Web Service tries a maximum of 10 times to deliver the invoke message from the JMS queue to the Web Service implementation, waiting 10 seconds between each retry. Only the relevant Java code is shown in the following snippet:

package examples.webservices.buffered;
...
@WebService(name="BufferedPortType",
            serviceName="BufferedService",
            targetNamespace="http://example.org")
@BufferQueue(name="my.buffer.queue")
public class BufferedImpl {
...
  @WebMethod()
  @MessageBuffer(retryCount=10, retryDelay="10 seconds")
  @Oneway()
  public void sayHelloNoReturn(String message) {
    System.out.println("sayHelloNoReturn: " + message);
  }
}

weblogic.jws.Policies

The following sections describe the annotation in detail.

Description

Target: Class, Method

Specifies an array of @weblogic.jws.Policy annotations.

Use this annotation if you want to attach more than one WS-Policy files to a class or method of a JWS file. If you want to attach just one WS-Policy file, you can use the @weblogic.jws.Policy on its own.

See Using Web Services Reliable Messaging in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server and Configuring Message-Level Security in Securing WebLogic Web Services for Oracle WebLogic Server for detailed information and examples of using this annotation.

This JWS annotation does not have any attributes.

Example
@Policies({
    @Policy(uri="policy:firstPolicy.xml"),
    @Policy(uri="policy:secondPolicy.xml")
  })

weblogic.jws.Policy

The following sections describe the annotation in detail.

Description

Target: Class, Method

Specifies that a WS-Policy file, which contains information about digital signatures, encryption, or Web Service reliable messaging, should be applied to the request or response SOAP messages.

This annotation can be used on its own to apply a single WS-Policy file to a class or method. If you want to apply more than one WS-Policy file to a class or method, use the @weblogic.jws.Policies annotation to group them together.

If this annotation is specified at the class level, the indicated WS-Policy file or files are applied to every public operation of the Web Service. If the annotation is specified at the method level, then only the corresponding operation will have the WS-Policy file applied.

By default, WS-Policy files are applied to both the request (inbound) and response (outbound) SOAP messages. You can change this default behavior with the direction attribute.

Also by default, the specified WS-Policy file is attached to the generated and published WSDL file of the Web Service so that consumers can view all the WS-Policy requirements of the Web Service. Use the attachToWsdl attribute to change this default behavior.

See Using Web Services Reliable Messaging in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server and Configuring Message-Level Security in Securing WebLogic Web Services for Oracle WebLogic Server for detailed information and examples of using this annotation.

Attributes

Table 3-17 Attributes of the weblogic.jws.Policy JWS Annotation Tag

Name Description Data Type Required?

uri

Specifies the location from which to retrieve the WS-Policy file.

Use the http: prefix to specify the URL of a WS-Policy file on the Web.

Use the policy: prefix to specify that the WS-Policy file is packaged in the Web Service archive file or in a shareable Java EE library of WebLogic Server, as shown in the following example:

@Policy(uri="policy:MyPolicyFile.xml")

If you are going to publish the WS-Policy file in the Web Service archive, the WS-Policy XML file must be located in either the META-INF/policies or WEB-INF/policies directory of the EJB JAR file (for EJB implemented Web Services) or WAR file (for Java class implemented Web Services), respectively.

For information on publishing the WS-Policy file in a library, see Creating Shared Java EE Libraries and Optional Packages in Developing Applications for Oracle WebLogic Server.

String

Yes

direction

Specifies when to apply the policy: on the inbound request SOAP message, the outbound response SOAP message, or both (default).

Valid values for this attribute are:

  • Policy.Direction.both

  • Policy.Direction.inbound

  • Policy.Direction.outbound

The default value is Policy.Direction.both.

enum

No

attachToWsdl

Specifies whether the WS-Policy file should be attached to the WSDL that describes the Web Service.

Valid values are true and false. Default value is false.

boolean

No

Example
  @Policy(uri="policy:myPolicy.xml", 
          attachToWsdl=true, 
          direction=Policy.Direction.outbound)

weblogic.jws.ReliabilityBuffer

The following sections describe the annotation in detail.

Description

Target: Method

Specifies reliable messaging properties for an operation of a reliable Web Service, such as the number of times WebLogic Server should attempt to deliver the message from the JMS queue to the Web Service implementation, and the amount of time that the server should wait in between retries.

Note:

It is assumed when you specify this annotation in a JWS file that you have already enabled reliable messaging for the Web Service by also including a @Policy annotation that specifies a WS-Policy file that has Web Service reliable messaging policy assertions.

If you specify the @ReliabilityBuffer annotation, but do not enable reliable messaging with an associated WS-Policy file, then WebLogic Server ignores this annotation.

See Using Web Services Reliable Messaging in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for detailed information about enabling Web Services reliable messaging for your Web Service.

Attributes

Table 3-18 Attributes of the weblogic.jws.ReliabilityBuffer JWS Annotation Tag

Name Description Data Type Required?

retryCount

Specifies the number of times that the JMS queue on the destination WebLogic Server instance attempts to deliver the message from a client that invokes the reliable operation to the Web Service implementation.

Default value is 3.

int

No

retryDelay

Specifies the amount of time that elapses between message delivery retry attempts. The retry attempts are between the client's request message on the JMS queue and delivery of the message to the Web Service implementation.

Valid values are a number and one of the following terms:

  • seconds

  • minutes

  • hours

  • days

  • years

For example, to specify a retry delay of two days, specify:

@ReliabilityBuffer(retryDelay="2 days")

Default value is 5 seconds.

String

No

Example

The following sample snippet shows how to use the @ReliabilityBuffer annotation at the method-level to change the default retry count and delay of a reliable operation; only relevant Java code is shown:

package examples.webservices.reliable;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.Oneway;

...
import weblogic.jws.ReliabilityBuffer;
import weblogic.jws.Policy;
@WebService(name="ReliableHelloWorldPortType",
              serviceName="ReliableHelloWorldService")

...
@Policy(uri="ReliableHelloWorldPolicy.xml",
          direction=Policy.Direction.inbound,
          attachToWsdl=true)
public class ReliableHelloWorldImpl {
  @WebMethod()
  @Oneway()
  @ReliabilityBuffer(retryCount=10, retryDelay="10 seconds")
  public void helloWorld(String input) {
    System.out.println(" Hello World " + input);
  }
}

weblogic.jws.ReliabilityErrorHandler

The following sections describe the annotation in detail.

Description

Target: Method

Specifies the method that handles the error that results when a client Web Service invokes a reliable Web Service, but the client does not receive an acknowledgement that the reliable Web Service actually received the message.

This annotation is relevant only when you implement the Web Service reliable messaging feature; you specify the annotation in the client-side Web Service that invokes a reliable Web Service.

The method you annotate with the @ReliabilityErrorHandler annotation takes a single parameter of data type weblogic.wsee.reliability.ReliabilityErrorContext. You can use this context to get more information about the cause of the error, such as the operation that caused it, the target Web Service, the fault, and so on. The method must return void.

The single attribute of the @ReliabilityErrorHandler annotation specifies the variable into which you have previously injected the stub information of the reliable Web Service that the client Web Service is invoking; you inject this information in a variable using the @weblogic.jws.ServiceClient annotation.

Attributes

Table 3-19 Attributes of the weblogic.jws.ReliabilityErrorHandler JWS Annotation Tag

Name Description Data Type Required?

target

Specifies the target stub name for which this method handles reliability failures.

String

Yes

Example

The following code snippet from a client Web Service that invokes a reliable Web Service shows how to use the @ReliabilityErrorHandler annotation; not all code is shown, and the code relevant to this annotation is shown in bold:

package examples.webservices.reliable;
...
import weblogic.jws.ServiceClient;
import weblogic.jws.ReliabilityErrorHandler;
import examples.webservices.reliable.ReliableHelloWorldPortType;
import weblogic.wsee.reliability.ReliabilityErrorContext;
import weblogic.wsee.reliability.ReliableDeliveryException;
@WebService(name="ReliableClientPortType",
...
public class ReliableClientImpl
{
  @ServiceClient(
     wsdlLocation="http://localhost:7001/ReliableHelloWorld/ReliableHelloWorld?WSDL",
     serviceName="ReliableHelloWorldService",
     portName="ReliableHelloWorldServicePort")
  private ReliableHelloWorldPortType port;
  @WebMethod
  public void callHelloWorld(String input, String serviceUrl)
     throws RemoteException {
   ...
  }
  @ReliabilityErrorHandler(target="port")
  public void onReliableMessageDeliveryError(ReliabilityErrorContext ctx) {
    ReliableDeliveryException fault = ctx.getFault();
    String message = null;
    if (fault != null) {
      message = ctx.getFault().getMessage();
    }
    String operation = ctx.getOperationName();
    System.out.println("Reliable operation " + operation + " may have not invoked. The error message is " + message);
  }
}

In the example, the port variable has been injected with the stub that corresponds to the ReliableHelloWorldService Web Service, and it is assumed that at some point in the client Web Service an operation of this stub is invoked. Because the onReliableMessageDeliveryError method is annotated with the @ReliabilityErrorHandler annotation and is linked with the port stub, the method is invoked if there is a failure in an invoke of the reliable Web Service. The reliable error handling method uses the ReliabilityErrorContext object to get more details about the cause of the failure.

weblogic.jws.ServiceClient

The following sections describe the annotation in detail.

Description

Target: Field

Specifies that the annotated variable in the JWS file is a stub used to invoke another WebLogic Web Service when using the following features:

  • Web Service reliable messaging

  • Asynchronous request-response

  • Conversations

You use the reliable messaging and asynchronous request-response features only between two Web Services; this means, for example, that you can invoke a reliable Web Service operation only from within another Web Service, not from a stand-alone client. In the case of reliable messaging, the feature works between any two application servers that implement the WS-ReliableMessaging specification at http://docs.oasis-open.org/ws-rx/wsrm/200702/wsrm-1.1-spec-os-01.pdf. In the case of asynchronous request-response, the feature works only between two WebLogic Server instances.

You use the @ServiceClient annotation in the client Web Service to specify which variable is a port type for the Web Service described by the @ServiceClient attributes. The Enterprise Application that contains the client Web Service must also include the stubs of the Web Service you are invoking; you generate the stubs with the clientgen Ant task.

See Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for additional information and examples of using the @ServiceClient annotation.

Attributes

Table 3-20 Attributes of the weblogic.jws.ServiceClient JWS Annotation Tag

Name Description Data Type Required?

serviceName

Specifies the name of the Web Service that you are invoking. Corresponds to the name attribute of the <service> element in the WSDL of the invoked Web Service.

If you used a JWS file to implement the invoked Web Service, this attribute corresponds to the serviceName attribute of the @WebService JWS annotation in the invoked Web Service.

String

Yes

portName

Specifies the name of the port of the Web Service you are invoking. Corresponds to the name attribute of the <port> child element of the <service> element.

If you used a JWS file to implement the invoked Web Service, this attribute corresponds to the portName attribute of the @WLHttpTransport JWS annotation in the invoked Web Service.

If you do not specify this attribute, it is assumed that the <service> element in the WSDL contains only one <port> child element, which @ServiceClient uses. If there is more than one port, the client Web Service returns a runtime exception.

String

No

wsdlLocation

Specifies the WSDL file that describes the Web Service you are invoking.

If you do not specify this attribute, the client Web Service uses the WSDL file from which the clientgen Ant task created the Service implementation of the Web Service to be invoked.

String

No

endpointAddress

Specifies the endpoint address of the Web Service you are invoking.

If you do not specify this attribute, the client Web Service uses the endpoint address specified in the WSDL file.

String

No

Example

The following JWS file excerpt shows how to use the @ServiceClient annotation in a client Web Service to annotate a field (port) with the stubs of the Web Service being invoked (called ReliableHelloWorldService whose WSDL is at the URL http://localhost:7001/ReliableHelloWorld/ReliableHelloWorld?WSDL); only relevant parts of the example are shown:

package examples.webservices.reliable;
import javax.jws.WebService;
...
import weblogic.jws.ServiceClient;
import examples.webservices.reliable.ReliableHelloWorldPortType;
@WebService(...
public class ReliableClientImpl
{
  @ServiceClient(
     wsdlLocation="http://localhost:7001/ReliableHelloWorld/ReliableHelloWorld?WSDL",
     serviceName="ReliableHelloWorldService",
     portName="ReliableHelloWorldServicePort")
  private ReliableHelloWorldPortType port;
  @WebMethod
  public void callHelloWorld(String input, String serviceUrl)
     throws RemoteException {
    port.helloWorld(input);
    System.out.println(" Invoked the ReliableHelloWorld.helloWorld operation reliably." );
  }
}

weblogic.jws.StreamAttachments

The following sections describe the annotation in detail.

Description

Target: Class

Specifies that the WebLogic Web Services runtime use streaming APIs when reading the parameters of all methods of the Web Service. This increases the performance of Web Service operation invocation, in particular when the parameters are large, such as images.

You cannot use this annotation if you are also using the following features in the same Web Service:

  • Conversations

  • Reliable Messaging

  • JMS Transport

  • A proxy server between the client application and the Web Service it invokes

The @StreamAttachments annotation does not have any attributes.

Example

The following simple JWS file shows how to specify the @StreamAttachments annotation; the single method, echoAttachment(), simply takes a DataHandler parameter and echoes it back to the client application that invoked the Web Service operation. The WebLogic Web Services runtime uses streaming when reading the DataHandler content.

package examples.webservices.stream_attach;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.StreamAttachments;
import javax.activation.DataHandler;
import java.rmi.RemoteException;
@WebService(name="StreamAttachPortType",
            serviceName="StreamAttachService",
            targetNamespace="http://example.org")
@WLHttpTransport(contextPath="stream_attach",
                 serviceUri="StreamAttachService",
                 portName="StreamAttachServicePort")
@StreamAttachments
/**
 * Example of stream attachments
 */
public class StreamAttachImpl {
  @WebMethod()
  public DataHandler echoAttachment(DataHandler dh) throws RemoteException {
        return dh;
  }
}

weblogic.jws.Transactional

The following sections describe the annotation in detail.

Description

Target: Class, Method

Specifies whether the annotated operation, or all the operations of the JWS file when the annotation is specified at the class-level, runs or run inside of a transaction. By default, the operations do not run inside of a transaction.

Attributes

Table 3-21 Attributes of the weblogic.jws.Transactional JWS Annotation Tag

Name Description Data Type Required?

value

Specifies whether the operation (when used at the method level) or all the operations of the Web Service (when specified at the class level) run inside of a transaction.

Valid values are true and false. Default value is false.

boolean

No

timeout

Specifies a timeout value, in seconds, for the current transaction.

The default value for this attribute is 30 seconds.

int

No

Example

The following example shows how to use the @Transactional annotation to specify that an operation of a Web Service executes as part of a transaction:

package examples.webservices.transactional;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.Transactional;
@WebService(name="TransactionPojoPortType",
            serviceName="TransactionPojoService",
            targetNamespace="http://example.org")
@WLHttpTransport(contextPath="transactionsPojo",
                 serviceUri="TransactionPojoService",
                 portName="TransactionPojoPort")
/**
 * This JWS file forms the basis of simple WebLogic
 * Web Service with a single operation: sayHello.  The operation executes
 * as part of a transaction.
*/
public class TransactionPojoImpl {
  @WebMethod()
  @Transactional(value=true)
  public String sayHello(String message) {
    System.out.println("sayHello:" + message);
    return "Here is the message: '" + message + "'";
  }
}

weblogic.jws.Types

The following sections describe the annotation in detail.

Description

Target: Method, Parameter

Specifies a comma-separated list of fully qualified Java class names of the alternative data types for a return type or parameter. The alternative data types must extend the data type specified in the method signature; if this is not the case, the jwsc Ant task returns a validation error when you compile the JWS file into a Web Service.

For example, assume you have created the Address base data type, and then created USAAddress and CAAddress that extend this base type. If the method signature specifies that it takes an Address parameter, you can annotate the parameter with the @Types annotation to specify that the public operation also takes USAAddress and CAAddress as a parameter, in addition to the base Address data type.

You can also use this annotation to restrict the data types that can be contained in parameters or return values of collection data types, such as java.util.Collection or java.util.List. By restricting the allowed contained data types, the generated WSDL is specific and unambiguous, and the Web Services runtime can do a better job of qualifying the parameters when a client application invokes a Web Service operation.

If you specify this annotation at the method-level, then it applies only to the return value. If you want the annotation to apply to parameters, you must specify it at the parameter-level for each relevant parameter.

Attributes

Table 3-22 Attributes of the weblogic.jws.Types JWS Annotation Tag

Name Description Data Type Required?

value

Comma-separated list of fully qualified class names for either the alternative data types that can also be used instead of the original data type, or the allowed data types contained in the collection-type parameter or return value.

String[]

Yes

Example

The following example shows a simple JWS file that uses the @Types annotation, with relevant Java code shown in bold:

package examples.webservices.types;
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.WLHttpTransport;
import weblogic.jws.Types;
import examples.webservices.types.BasicStruct;
@WebService(serviceName="TypesService",
            name="TypesPortType",
            targetNamespace="http://example.org")
@WLHttpTransport(contextPath="types",
                 serviceUri="TypesService",
                 portName="TypesServicePort")
public class TypesImpl {
  @WebMethod()
  @Types({"examples.webservices.types.ExtendedStruct"})
  public BasicStruct echoStruct(
     @Types({"examples.webservices.types.ExtendedStruct"}) BasicStruct struct)
  {
    System.out.println("echoStruct called");
    return struct;
  }
}

In the example, the signature of the echoStruct() method shows that it takes a BasicStruct value as both a parameter and a return value. However, because both the method and the struct parameter are annotated with the @Types annotation, a client application invoking the echoStruct operation can also pass it a parameter of data type ExtendedStruct; in this case the operation also returns an ExtendedStruct value. It is assumed that ExtendedStruct extends BasicStruct.

weblogic.jws.WildcardBinding

The following sections describe the annotation in detail.

Description

Target: Class

Specifies the XML Schema data type to which a wildcard class, such as javax.xml.soap.SOAPElement or org.apache.xmlbeans.XmlObject, binds. By default, these Java data types bind to the <xsd:any> XML Schema data type. By using this class-level annotation, you can specify that the wildcard classes bind to <xsd:anyType> instead.

Attributes

Table 3-23 Attributes of the weblogic.jws.WildcardBinding JWS Annotation Tag

Name Description Data Type Required?

className

Specifies the fully qualified name of the wildcard class for which this binding applies. Typical values are javax.xml.soap.SOAPElement and org.apache.xmlbeans.XmlObject.

String

Yes

binding

Specifies the XML Schema data type to which the wildcard class should bind.

You can specify one of the following values:

  • WildcardParticle.ANY

  • WildcardParticle.ANYTYPE

enum

Yes

Example

The following example shows how to use the @WildcardBinding annotation to specify that the Apache XMLBeans data type XMLObject should bind to the <xsd:any> XML Schema data type for this Web Service:

@WildcardBindings({
    @WildcardBinding(className="org.apache.xmlbeans.XmlObject", 
                      binding=WildcardParticle.ANY),
    @WildcardBinding(className="org.apache.xmlbeans.XmlObject[]",
                      binding=WildcardParticle.ANY)})
public class SimpleImpl {
...

weblogic.jws.WildcardBindings

The following sections describe the annotation in detail.

Description

Target: Class

Specifies an array of @weblogic.jws.WildcardBinding annotations.

This JWS annotation does not have any attributes.

See weblogic.jws.WildcardBinding for an example.

weblogic.jws.WLHttpTransport (Deprecated)

The following sections describe the annotation in detail.

Description

Target: Class

Specifies the context path and service URI sections of the URL used to invoke the Web Service over the HTTP transport, as well as the name of the port in the generated WSDL.

You can specify this annotation only once (maximum) in a JWS file.

Attributes

Table 3-24 Attributes of the weblogic.jws.WLHttpTransport JWS Annotation Tag

Name Description Data Type Required?

contextPath

Context path of the Web Service. You use this value in the URL that invokes the Web Service.

For example, assume you set the context path for a Web Service to financial; a possible URL for the WSDL of the deployed WebLogic Web Service is as follows:

http://hostname:7001/financial/GetQuote?WSDL

The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is HelloWorldImpl.java, then the default value of its contextPath is HelloWorldImpl.

String

No

serviceUri

Web Service URI portion of the URL. You use this value in the URL that invokes the Web Service.

For example, assume you set this attribute to GetQuote; a possible URL for the deployed WSDL of the service is as follows:

http://hostname:7001/financial/GetQuote?WSDL

The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is HelloWorldImpl.java, then the default value of its serviceUri is HelloWorldImpl.

String

No

portName

The name of the port in the generated WSDL. This attribute maps to the name attribute of the <port> element in the WSDL.

The default value of this attribute is based on the @javax.jws.WebService annotation of the JWS file. In particular, the default portName is the value of the name attribute of @WebService annotation, plus the actual text SoapPort. For example, if @WebService.name is set to MyService, then the default portName is MyServiceSoapPort.

String

No

Example
@WLHttpTransport(contextPath="complex", 
                 serviceUri="ComplexService",
                 portName="ComplexServicePort")

weblogic.jws.WLHttpsTransport

The following sections describe the annotation in detail.

Description

Target: Class

Note:

The @weblogic.jws.WLHttpsTransport annotation is deprecated as of version 9.2 of WebLogic Server. You should use the @weblogic.jws.WLHttpTransport annotation instead because it now supports both the HTTP and HTTPS protocols. If you want client applications to access the Web Service using only the HTTPS protocol, then you must specify the @weblogic.jws.security.UserDataConstraint JWS annotation in your JWS file.

Specifies the context path and service URI sections of the URL used to invoke the Web Service over the HTTPS transport, as well as the name of the port in the generated WSDL.

You can specify this annotation only once (maximum) in a JWS file.

Attributes

Table 3-25 Attributes of the weblogic.jws.WLHttpsTransport JWS Annotation Tag

Name Description Data Type Required?

contextPath

Context path of the Web Service. You use this value in the URL that invokes the Web Service.

For example, assume you set the context path for a Web Service to financial; a possible URL for the WSDL of the deployed WebLogic Web Service is as follows:

https://hostname:7001/financial/GetQuote?WSDL

The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is HelloWorldImpl.java, then the default value of its contextPath is HelloWorldImpl.

String

No

serviceUri

Web Service URI portion of the URL. You use this value in the URL that invokes the Web Service.

For example, assume you set this attribute to GetQuote; a possible URL for the deployed WSDL of the service is as follows:

https://hostname:7001/financial/GetQuote?WSDL

The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is HelloWorldImpl.java, then the default value of its serviceUri is HelloWorldImpl.

String

No

portName

The name of the port in the generated WSDL. This attribute maps to the name attribute of the <port> element in the WSDL.

The default value of this attribute is based on the @javax.jws.WebService annotation of the JWS file. In particular, the default portName is the value of the name attribute of @WebService annotation, plus the actual text SoapPort. For example, if @WebService.name is set to MyService, then the default portName is MyServiceSoapPort.

String

No

Example
@WLHttpsTransport(portName="helloSecurePort",
                 contextPath="secure",
                 serviceUri="SimpleSecureBean")

weblogic.jws.WLJmsTransport

The following sections describe the annotation in detail.

Description

Target: Class

Specifies the context path and service URI sections of the URL used to invoke the Web Service over the JMS transport, as well as the name of the port in the generated WSDL. You also use this annotation to specify the JMS queue to which WebLogic Server queues the SOAP request messages from invokes of the operations.

You can specify this annotation only once (maximum) in a JWS file.

Attributes

Table 3-26 Attributes of the weblogic.jws.WLJmsTransport JWS Annotation Tag

Name Description Data Type Required?

contextPath

Context path (or context root) of the Web Service. You use this value in the URL that invokes the Web Service.

String

No

serviceUri

Web Service URI portion of the URL used by client applications to invoke the Web Service.

String

No

queue

The JNDI name of the JMS queue that you have configured for the JMS transport. See Using JMS Transport as the Connection Protocol in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for details about using JMS transport.

The default value of this attribute, if you do not specify it, is weblogic.wsee.DefaultQueue. You must still create this JMS queue in the WebLogic Server instance to which you deploy your Web Service.

String

No

portName

The name of the port in the generated WSDL. This attribute maps to the name attribute of the <port> element in the WSDL.

If you do not specify this attribute, the jwsc generates a default name based on the name of the class that implements the Web Service.

String

No

connectionFactory

The JNDI name of the JMS connection factory that you have configured for the JMS transport. See Using JMS Transport as the Connection Protocol in Oracle Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server for details about using JMS transport.

String

Yes

Example

The following example shows how to specify that the JWS file implements a Web Service that is invoked using the JMS transport. The JMS queue to which WebLogic Server queues SOAP message requests from invokes of the service operations is JMSTransportQueue; it is assumed that this JMS queue has already been configured for WebLogic Server.

WLJmsTransport(contextPath="transports", 
                serviceUri="JMSTransport",
                queue="JMSTransportQueue", 
                portName="JMSTransportServicePort")

weblogic.jws.WSDL

The following sections describe the annotation in detail.

Description

Target: Class

Specifies whether to expose the WSDL of a deployed WebLogic Web Service.

By default, the WSDL is exposed at the following URL:

http://[host]:[port]/[contextPath]/[serviceUri]?WSDL

where:

  • host refers to the computer on which WebLogic Server is running.

  • port refers to the port number on which WebLogic Server is listening (default value is 7001).

  • contextPath and serviceUri refer to the value of the contextPath and serviceUri attributes, respectively, of the @WLHttpTransport JWS annotation of the JWS file that implements your Web Service.

For example, assume you used the following @WLHttpTransport annotation:

@WLHttpTransport(portName="helloPort",
                 contextPath="hello",
                 serviceUri="SimpleImpl")

The URL to get view the WSDL of the Web Service, assuming the service is running on a host called ariel at the default port number, is:

http://ariel:7001/hello/SimpleImpl?WSDL
Attributes

Table 3-27 Attributes of the weblogic.jws.WSDL JWS Annotation Tag

Name Description Data Type Required?

exposed

Specifies whether to expose the WSDL of a deployed Web Service.

Valid values are true and false. Default value is true, which means that by default the WSDL is exposed.

boolean

No

Example

The following use of the @WSDL annotation shows how to specify that the WSDL of a deployed Web Service not be exposed; only relevant Java code is shown:

package examples.webservices;
import weblogic.jws.WSDL;
@WebService(name="WsdlAnnotationPortType",
            serviceName="WsdlAnnotationService",
            targetNamespace="http://example.org")
@WSDL(exposed=false)
public class WsdlAnnotationImpl {
...
}

weblogic.jws.security.CallbackRolesAllowed

The following sections describe the annotation in detail.

Description

Target: Method, Field

Specifies an array of @SecurityRole JWS annotations that list the roles that are allowed to invoke the callback methods of the Web Service. A user that is mapped to an unspecified role, or is not mapped to any role at all, would not be allowed to invoke the callback methods.

If you use this annotation at the field level, then the specified roles are allowed to invoke all callback operations of the Web Service. If you use this annotation at the method-level, then the specified roles are allowed to invoke only that callback method. If specified at both levels, the method value overrides the field value if there is a conflict.

Attributes

Table 3-28 Attributes of the weblogic.jws.security.CallbackRolesAllowed JWS Annotation Tag

Name Description Data Type Required?

value

Array of @we3blogic.jws.security.RolesAllowed that list the roles allowed to invoke the callback methods.

String[]

Yes

Example

The following example shows how to use the @CallbackRolesAllowed annotation at the method level to specify that the role engineer is allowed to invoke the callback method:

@CallbackMethod(target="port", operation="callbackOperation")
@CallbackRolesAllowed(@SecurityRole(role="engineer", mapToPrincipals="shackell"))
public void callbackHandler(String msg) {
      System.out.println (msg);
}

we3blogic.jws.security.RolesAllowed

The following sections describe the annotation in detail.

Description

Target: Class, Method

Specifies whether to enable basic authentication for a Web Service. In particular, it specifies an array of @SecurityRole JWS annotations that describe the list of roles that are allowed to invoke the Web Service. A user that is mapped to an unspecified role, or is not mapped to any role at all, would not be allowed to invoke the Web Service.

If you use this annotation at the class-level, then the specified roles are allowed to invoke all operations of the Web Service. To specify roles for just a specific set of operations, specify the annotation at the operation-level.

Attributes

Table 3-29 Attributes of the weblogic.jws.security.RolesAllowed JWS Annotation Tag

Name Description Data Type Required?

value

Array of @we3blogic.jws.security.RolesAllowed that list the roles allowed to invoke the Web Service methods.

String[]

Yes

Example
package examples.webservices.security_roles;
...
import weblogic.jws.security.RolesAllowed;
import weblogic.jws.security.SecurityRole;
@WebService(name="SecurityRolesPortType",
            serviceName="SecurityRolesService",
            targetNamespace="http://example.org")
@RolesAllowed (  {
    @SecurityRole (role="manager",
                   mapToPrincipals={ "juliet","amanda" }),
    @SecurityRole (role="vp")
} )
public class SecurityRolesImpl {
...

In the example, only the roles manager and vp are allowed to invoke the Web Service. Within the context of the Web Service, the users juliet and amanda are assigned the role manager. The role vp, however, does not include a mapToPrincipals attribute, which implies that users have been mapped to this role externally. It is assumed that you have already added the two users (juliet and amanda) to the WebLogic Server security realm.

weblogic.jws.security.RolesReferenced

Description

Target: Class

Specifies the list of role names that reference actual roles that are allowed to invoke the Web Service. In particular, it specifies an array of @SecurityRoleRef JWS annotations, each of which describe a link between a referenced role name and an actual role defined by a @SecurityRole annotation.

This JWS annotation does not have any attributes.

Example
package examples.webservices.security_roles;
...
import weblogic.jws.security.RolesAllowed;
import weblogic.jws.security.SecurityRole;
import weblogic.jws.security.RolesReferenced;
import weblogic.jws.security.SecurityRoleRef;
@WebService(name="SecurityRolesPortType",
            serviceName="SecurityRolesService",
            targetNamespace="http://example.org")
@RolesAllowed (  {
    @SecurityRole (role="manager",
                   mapToPrincipals={ "juliet","amanda" }),
    @SecurityRole (role="vp")
} )
@RolesReferenced (
    @SecurityRoleRef (role="mgr", link="manager")
)
public class SecurityRolesImpl {
...

In the example, the role mgr is linked to the role manager, which is allowed to invoke the Web Service. This means that any user who is assigned to the role of mgr is also allowed to invoke the Web Service.

weblogic.jws.security.RunAs

The following sections describe the annotation in detail.

Description

Target: Class

Specifies the role and user identity which actually runs the Web Service in WebLogic Server.

For example, assume that the @RunAs annotation specifies the roleA role and userA principal. This means that even if the Web Service is invoked by userB (mapped to roleB), the relevant operation is actually executed internal as userA.

Attributes

Table 3-30 Attributes of the weblogic.jws.security.RunAs JWS Annotation

Name Description Data Type Required?

role

Specifies the role which the Web Service should be run as.

String

Yes

mapToPrincipal

Specifies the principal user that maps to the role.

It is assumed that you have already configured the specified principal (user) as a valid WebLogic Server user, typically using the WebLogic Server Administration Console. See Create users in the Oracle WebLogic Server Administration Console Online Help for details.

String

Yes

Example
package examples.webservices.security_roles;
import weblogic.jws.security.RunAs;
...
@WebService(name="SecurityRunAsPortType",
            serviceName="SecurityRunAsService",
            targetNamespace="http://example.org")
@RunAs (role="manager", mapToPrincipal="juliet")
public class SecurityRunAsImpl {
...

The example shows how to specify that the Web Service is always run as user juliet, mapped to the role manager, regardless of who actually invoked the Web Service.

weblogic.jws.security.SecurityRole

The following sections describe the annotation in detail.

Description

Target: Class, Method

Specifies the name of a role that is allowed to invoke the Web Service. This annotation is always specified in the JWS file as a member of a @RolesAllowed array.

When a client application invokes the secured Web Service, it specifies a user and password as part of its basic authentication. It is assumed that an administrator has already configured the user as a valid WebLogic Server user using the WebLogic Server Administration Console; for details see Create Users in the Oracle WebLogic Server Administration Console Online Help.

The user that is going to invoke the Web Service must also be mapped to the relevant role. You can perform this task in one of the following two ways:

  • Use the WebLogic Server Administration Console to map the user to the role. In this case, you do not specify the mapToPrincipals attribute of the @SecurityRole annotation. See Add Users to Roles in the Oracle WebLogic Server Administration Console Online Help.

  • Map the user to a role only within the context of the Web Service by using the mapToPrincipals attribute to specify one or more users.

To specify that multiple roles are allowed to invoke the Web Service, include multiple @SecurityRole annotations within the @RolesAllowed annotation.

Attributes

Table 3-31 Attributes of the weblogic.jws.security.SecurityRole JWS Annotation

Name Description Data Type Required?

role

The name of the role that is allowed to invoke the Web Service.

String

Yes

mapToPrincipals

An array of user names that map to the role.

If you do not specify this attribute, it is assumed that you have externally defined the mapping between users and the role, typically using the WebLogic Server Administration Console.

String[]

No

Example
package examples.webservices.security_roles;
...
import weblogic.jws.security.RolesAllowed;
import weblogic.jws.security.SecurityRole;
@WebService(name="SecurityRolesPortType",
            serviceName="SecurityRolesService",
            targetNamespace="http://example.org")
@RolesAllowed (  {
    @SecurityRole (role="manager",
                   mapToPrincipals={ "juliet","amanda" }),
    @SecurityRole (role="vp")
} )
public class SecurityRolesImpl {
...

In the example, only the roles manager and vp are allowed to invoke the Web Service. Within the context of the Web Service, the users juliet and amanda are assigned the role manager. The role vp, however, does not include a mapToPrincipals attribute, which implies that users have been mapped to this role externally. It is assumed that you have already added the two users (juliet and amanda) to the WebLogic Server security realm.

weblogic.jws.security.SecurityRoleRef

The following sections describe the annotation in detail.

Description

Target: Class

Specifies a role name reference that links to an already-specified role that is allowed to invoke the Web Service.

Users that are mapped to the role reference can invoke the Web Service as long as the referenced role is specified in the @RolesAllowed annotation of the Web Service.

Attributes

Table 3-32 Attributes of the weblogic.jws.security.SecurityRoleRef JWS Annotation

Name Description Data Type Required?
role

Name of the role reference.

String

Yes

link

Name of the already-specified role that is allowed to invoke the Web Service. The value of this attribute corresponds to the value of the role attribute of a @SecurityRole annotation specified in the same JWS file.

String

Yes

Example
package examples.webservices.security_roles;
...
import weblogic.jws.security.RolesAllowed;
import weblogic.jws.security.SecurityRole;
import weblogic.jws.security.RolesReferenced;
import weblogic.jws.security.SecurityRoleRef;
@WebService(name="SecurityRolesPortType",
            serviceName="SecurityRolesService",
            targetNamespace="http://example.org")
@RolesAllowed (  {
    @SecurityRole (role="manager",
                   mapToPrincipals={ "juliet","amanda" }),
    @SecurityRole (role="vp")
} )
@RolesReferenced (
    @SecurityRoleRef (role="mgr", link="manager")
)
public class SecurityRolesImpl {
...

In the example, the role mgr is linked to the role manager, which is allowed to invoke the Web Service. This means that any user who is assigned to the role of mgr is also allowed to invoke the Web Service.

weblogic.jws.security.UserDataConstraint

The following sections describe the annotation in detail.

Description

Target: Class

Specifies whether the client is required to use the HTTPS transport when invoking the Web Service.

WebLogic Server establishes a Secure Sockets Layer (SSL) connection between the client and Web Service if the transport attribute of this annotation is set to either Transport.INTEGRAL or Transport.CONFIDENTIAL in the JWS file that implements the Web Service.

If you specify this annotation in your JWS file, you must also specify the weblogic.jws.WLHttpTransport (Deprecated) annotation (or the <WLHttpTransport> element of the jwsc Ant task) to ensure that an HTTPS binding is generated in the WSDL file by the jwsc Ant task.

Attributes

Table 3-33 Attributes of the weblogic.jws.security.UserDataConstraint JWS Annotation

Name Description Data Type Required?

transport

Specifies whether the client is required to use the HTTPS transport when invoking the Web Service.

Valid values are:

  • Transport.NONE—Specifies that the Web Service does not require any transport guarantees.

  • Transport.INTEGRAL—Specifies that the Web Service requires that the data be sent between the client and Web Service in such a way that it cannot be changed in transit.

  • Transport.CONFIDENTIAL—Specifies that the Web Service requires that data be transmitted so as to prevent other entities from observing the contents of the transmission.

Default value is Transport.NONE.

enum

No

Example
package examples.webservices.security_https;
import weblogic.jws.security.UserDataConstraint;
...
@WebService(name="SecurityHttpsPortType",
            serviceName="SecurityHttpsService",
            targetNamespace="http://example.org")
@UserDataConstraint(
           transport=UserDataConstraint.Transport.CONFIDENTIAL)
public class SecurityHttpsImpl {
...

weblogic.jws.security.WssConfiguration

The following sections describe the annotation in detail.

Description

Target: Class

Specifies the name of the Web Service security configuration you want the Web Service to use. If you do not specify this annotation in your JWS file, the Web Service is associated with the default security configuration (called default_wss) if it exists in your domain.

The @WssConfiguration annotation only makes sense if your Web Service is configured for message-level security (encryption and digital signatures). The security configuration, associated to the Web Service using this annotation, specifies information such as whether to use an X.509 certificate for identity, whether to use password digests, the keystore to be used for encryption and digital signatures, and so on.

WebLogic Web Services are not required to be associated with a security configuration; if the default behavior of the Web Services security runtime is adequate then no additional configuration is needed. If, however, a Web Service requires different behavior from the default (such as using an X.509 certificate for identity, rather than the default username/password token), then the Web Service must be associated with a security configuration.

Before you can successfully invoke a Web Service that specifies a security configuration, you must use the WebLogic Server Administration Console to create it. For details, see Create a Web Services security configuration in the Oracle WebLogic Server Administration Console Online Help. For general information about message-level security, see Configuring Message-Level Security in Securing WebLogic Web Services for Oracle WebLogic Server.

Note:

All WebLogic Web Services packaged in a single Web Application must be associated with the same security configuration when using the @WssConfiguration annotation. This means, for example, that if a @WssConfiguration annotation exists in all the JWS files that implement the Web Services contained in a given Web Application, then the value attribute of each @WssConfiguration must be the same.

To specify that more than one Web Service be contained in a single Web Application when using the jwsc Ant task to compile the JWS files into Web Services, group the corresponding <jws> elements under a single <module> element.

Attributes

Table 3-34 Attributes of the weblogic.jws.security.WssConfiguration JWS Annotation Tag

Name Description Data Type Required?

value

Specifies the name of the Web Service security configuration that is associated with this Web Service. The default configuration is called default_wss.

You must create the security configuration (even the default one) using the WebLogic Server Administration Console before you can successfully invoke the Web Service.

String

Yes

Example

The following example shows how to specify that a Web Service is associated with the my_security_configuration security configuration; only the relevant Java code is shown:

package examples.webservices.wss_configuration;
import javax.jws.WebService;
...
import weblogic.jws.security.WssConfiguration;
@WebService(...
...
@WssConfiguration(value="my_security_configuration")
public class WssConfigurationImpl {
...

weblogic.jws.soap.SOAPBinding

The following sections describe the annotation in detail.

Description

Target: Method

Specifies the mapping of a Web Service operation onto the SOAP message protocol.

This annotation is analogous to @javax.jws.soap.SOAPBinding except that it applies to a method rather than the class. With this annotation you can specify, for example, that one Web Service operation uses RPC-encoded SOAP bindings and another operation in the same Web Service uses document-literal-wrapped SOAP bindings.

Note:

Because @weblogic.jws.soap.SOAPBinding and @javax.jws.soap.SOAPBinding have the same class name, be careful which annotation you are referring to when using it in your JWS file.

Attributes

Table 3-35 Attributes of the weblogic.jws.soap.SOAPBinding JWS Annotation

Name Description Data Type Required?

style

Specifies the message style of the request and response SOAP messages of the invoked annotated operation.

Valid values are:

  • SOAPBinding.Style.RPC

  • SOAPBinding.Style.DOCUMENT.

Default value is SOAPBinding.Style.DOCUMENT.

enum

No

use

Specifies the formatting style of the request and response SOAP messages of the invoked annotated operation.

Valid values are:

  • SOAPBinding.Use.LITERAL

  • SOAPBinding.Use.ENCODED

Default value is SOAPBinding.Use.LITERAL.

enum

No

parameterStyle

Determines whether method parameters represent the entire message body, or whether the parameters are elements wrapped inside a top-level element named after the operation.

Valid values are:

  • SOAPBinding.ParameterStyle.BARE

  • SOAPBinding.ParameterStyle.WRAPPED

Default value is SOAPBinding.ParameterStyle.WRAPPED

Note: This attribute applies only to Web Services of style document-literal. Or in other words, you can specify this attribute only if you have also set the style attribute to SOAPBinding.Style.DOCUMENT and the use attribute to SOAPBinding.Use.LITERAL.

enum

No

Example

The following simple JWS file shows how to specify that, by default, the operations of the Web Service use document-literal-wrapped SOAP bindings; you specify this by using the @javax.jws.soap.SOAPBinding annotation at the class-level. The example then shows how to specify different SOAP bindings for individual methods by using the @weblogic.jws.soap.SOAPBinding annotation at the method-level. In particular, the sayHelloDocLitBare() method uses document-literal-bare SOAP bindings, and the sayHelloRPCEncoded() method uses RPC-encoded SOAP bindings.

package examples.webservices.soap_binding_method;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import weblogic.jws.WLHttpTransport;
@WebService(name="SoapBindingMethodPortType",
            serviceName="SoapBindingMethodService",
            targetNamespace="http://example.org")
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
             use=SOAPBinding.Use.LITERAL,
             parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
@WLHttpTransport(contextPath="soap_binding_method",
                 serviceUri="SoapBindingMethodService",
                 portName="SoapBindingMethodServicePort")
/**
 * Simple JWS example that shows how to specify soap bindings for a method.
 */
public class SoapBindingMethodImpl {
  @WebMethod()
  @weblogic.jws.soap.SOAPBinding(
               style=SOAPBinding.Style.DOCUMENT,
               use=SOAPBinding.Use.LITERAL,
               parameterStyle=SOAPBinding.ParameterStyle.BARE)
  public String sayHelloDocLitBare(String message) {
    System.out.println("sayHelloDocLitBare" + message);
    return "Here is the message: '" + message + "'";
  }
  @WebMethod()
  @weblogic.jws.soap.SOAPBinding(
               style=SOAPBinding.Style.RPC,
               use=SOAPBinding.Use.ENCODED)
  public String sayHelloRPCEncoded (String message) {
    System.out.println("sayHelloRPCEncoded" + message);
    return "Here is the message: '" + message + "'";
  }
}

weblogic.jws.security.SecurityRoles (deprecated)

The following sections describe the annotation in detail.

Description

Target: Class, Method

Note:

The @weblogic.security.jws.SecurityRoles JWS annotation is deprecated beginning in WebLogic Server 9.0.

Specifies the roles that are allowed to access the operations of the Web Service.

If you specify this annotation at the class level, then the specified roles apply to all public operations of the Web Service. You can also specify a list of roles at the method level if you want to associate different roles to different operations of the same Web Service.

Note:

The @SecurityRoles annotation is supported only within the context of an EJB-implemented Web Service. For this reason, you can specify this annotation only inside of a JWS file that explicitly implements javax.ejb.SessionBean. See Securing Enterprise JavaBeans (EJBs) in Developing Applications with the WebLogic Security Service for conceptual information about what it means to secure access to an EJB. See Should You Implement a Stateless Session EJB? in Developing JAX-WS Web Services for Oracle WebLogic Server for information about explicitly implementing an EJB in a JWS file.

Attributes

Table 3-36 Attributes of the weblogic.jws.security.SecurityRoles JWS Annotation

Name Description Data Type Required?

rolesAllowed

Specifies the list of roles that are allowed to access the Web Service.

This annotation is the equivalent of the <method-permission> element in the ejb-jar.xml deployment descriptor of the stateless session EJB that implements the Web Service.

Array of String

No

rolesReferenced

Specifies a list of roles referenced by the Web Service.

The Web Service may access other resources using the credentials of the listed roles.

This annotation is the equivalent of the <security-role-ref> element in the ejb-jar.xml deployment descriptor of the stateless session EJB that implements the Web Service.

Array of String

No

Example

The following example shows how to specify, at the class-level, that the Web Service can be invoked only by the Admin role; only relevant parts of the example are shown:

package examples.webservices.security_roles;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
import weblogic.ejbgen.Session;
import javax.jws.WebService;
...
import weblogic.jws.security.SecurityRoles;
@Session(ejbName="SecurityRolesEJB")
@WebService(...
// Specifies the roles who can invoke the entire Web Service
@SecurityRoles(rolesAllowed="Admnin")
public class SecurityRolesImpl implements SessionBean {
...

weblogic.jws.security.SecurityIdentity (deprecated)

The following sections describe the annotation in detail.

Description

Target: Class

Note:

The @weblogic.security.jws.SecurityIdentity JWS annotation is deprecated beginning in WebLogic Server 9.1.

Specifies the identity assumed by the Web Service when it is invoked.

Unless otherwise specified, a Web Service assumes the identity of the authenticated invoker. This annotation allows the developer to override this behavior so that the Web Service instead executes as a particular role. The role must map to a user or group in the WebLogic Server security realm.

Note:

The @SecurityIdentity annotation only makes sense within the context of an EJB-implemented Web Service. For this reason, you can specify this annotation only inside of a JWS file that explicitly implements javax.ejb.SessionBean. See Securing Enterprise JavaBeans (EJBs) in Developing Applications with the WebLogic Security Service for conceptual information about what it means to secure access to an EJB. See Should You Implement a Stateless Session EJB? in Developing JAX-WS Web Services for Oracle WebLogic Server for information about explicitly implementing an EJB in a JWS file.

Attributes

Table 3-37 Attributes of the weblogic.jws.security.SecurityIdentity JWS Annotation

Name Description Data Type Required?

value

Specifies the role which the Web Service assumes when it is invoked. The role must map to a user or group in the WebLogic Server security realm.

String

Yes

Example

The following example shows how to specify that the Web Service, when invoked, runs as the Admin role:

package examples.webservices.security_roles;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
import weblogic.ejbgen.Session;
import javax.jws.WebService;
...
import weblogic.jws.security.SecurityIdentity;
@Session(ejbName="SecurityRolesEJB")
@WebService(...
// Specifies that the Web Service runs as the Admin role
@SecurityIdentity( value="Admin")
public class SecurityRolesImpl implements SessionBean {
...

weblogic.wsee.jws.jaxws.owsm.Property

The following sections describe the annotation in detail.

Description

Target: Class

Specifies a policy configuration property override.

Use this annotation with the weblogic.wsee.jws.jaxws.owsm.SecurityPolicy annotation to override a configuration property when attaching a policy to a web service client.

Note:

This annotation can be used for web service clients only. It is not supported for web service (server-side) policy attachment.

See Attaching Policies to Java EE Web Services and Clients Using Annotations in Securing Web Services and Managing Policies with Oracle Web Services Manager for detailed information and examples of using this annotation.

This JWS annotation does not have any attributes.

Example
@SecurityPolicy(uri="policy:oracle/wss10_message_protection_client_policy", 
          properties = { 
             @Property(name="keystore.recipient.alias", value="mykey")
          })

weblogic.wsee.jws.jaxws.owsm.SecurityPolicies

The following sections describe the annotation in detail.

Description

Target: Class

Specifies an array of @weblogic.wsee.jws.jaxws.owsm.SecurityPolicies annotations.

Use this annotation if you want to attach more than one OWSM security policy to the class of a JWS file. If you want to attach just one OWSM security policy, you can use the @weblogic.wsee.jws.jaxws.owsm.SecurityPolicy annotation.

See Attaching Policies to Java EE Web Services and Clients Using Annotations in Securing Web Services and Managing Policies with Oracle Web Services Manager for detailed information and examples of using this annotation.

This JWS annotation does not have any attributes.

Example
@SecurityPolicies({
    @SecurityPolicy(uri="oracle/wss_saml20_token_over_sll_service_policy"),
    @SecurityPolicy(uri="oracle/binding_authorization_permitall_policy")
  })

weblogic.wsee.jws.jaxws.owsm.SecurityPolicy

The following sections describe the annotation in detail.

Description

Target: Class

Attaches an OWSM security policy file to the web service or client.

This annotation can be used on its own to apply a single OWSM security policy to a class. If you want to attach more than one OWSM security policy to a class, use the @weblogic.wsee.jws.jaxws.owsm.SecurityPolicies annotation to group them together.

See Attaching Policies to Java EE Web Services and Clients Using Annotations in Securing Web Services and Managing Policies with Oracle Web Services Manager for detailed information and examples of using this annotation.

Attributes

Table 3-38 Attributes of the weblogic.wsee.jws.jaxws.owsm.SecurityPolicy JWS Annotation Tag

Name Description Data Type Required?

uri

Specifies the name of the OWSM security policy.

Use the policy: prefix to specify that the OWSM policy is packaged in the OWSM policy repository, as shown in the following example:

@SecurityPolicy(uri="policy:oracle/wss_saml20_token_over_ssl_service_policy")

For more information about the OWSM repository, see Managing the OWSM Repository in Securing Web Services and Managing Policies with Oracle Web Services Manager.

String

Yes

properties

Note: This attribute can be specified for web service clients only. This attribute is not supported for web service (server-side) policy attachment.

Specifies policy configuration override information. You specify one or more configuration property values using the weblogic.wsee.jws.jaxws.owsm.Property annotation, as described in weblogic.wsee.jws.jaxws.owsm.Property.

String

No

enabled

Specifies whether the OWSM policy file is enabled.

Valid values are true and false. Default value is true.

boolean

No

Examples

The following example shows how to attach the wss_saml20_token_over_ssl_service_policy to a web service.

@SecurityPolicy(uri="policy:oracle/wss_saml20_token_over_ssl_service_policy", 
          enabled=true)

The following example shows how to attach the wss10_message_protection_client_policy to a web service client and override the keystore.recipient.alias configuration property.

@SecurityPolicy(uri="policy:oracle/wss10_message_protection_client_policy", 
          properties = { 
             @Property(name="keystore.recipient.alias", value="mykey")
          },
          enabled=true)

weblogic.wsee.jws.jaxws.owsm.SecurityPolicies

The following sections describe the annotation in detail.

Description

Target: Class, Method

Specifies an array of @weblogic.wsee.jws.jaxws.owsm.SecurityPolicy annotations.

Use this annotation if you want to attach more than one Oracle Web Services Manager (Oracle WSM) WS-Policy files to a class or method of a JWS file. If you want to attach just one Oracle WSM WS-Policy file, you can use the @weblogic.wsee.jws.jaxws.owsm.SecurityPolicy on its own.

See Using Oracle Web Service Security Policies in Securing WebLogic Web Services for Oracle WebLogic Server for detailed information and examples of using this annotation.

This JWS annotation does not have any attributes.

Example
@SecurityPolicies({
    @SecurityPolicy(uri="policy:firstPolicy.xml"),
    @SecurityPolicy(uri="policy:secondPolicy.xml")
  })

weblogic.wsee.jws.jaxws.owsm.SecurityPolicy

The following sections describe the annotation in detail.

Description

Target: Class, Method

Specifies that an Oracle Web Services Manager (Oracle WSM) WS-Policy file, which contains information about digital signatures or encryption, should be applied to the request or response SOAP messages.

This annotation can be used on its own to apply a single Oracle WSM WS-Policy file to a class or method. If you want to apply more than one Oracle WSM WS-Policy file to a class or method, use the @weblogic.wsee.jws.jaxws.owms.SecurityPolicies annotation to group them together.

This annotation can be applied at the class level only, indicating that the Oracle WSM WS-Policy file or files are applied to every public operation of the Web Service.

The Oracle WSM WS-Security policies are not advertised in the WSDL of a WebLogic Server JAX-WS Web service. (Typically, the policy file associated with a Web service is attached to its WSDL, which the Web services client runtime reads to determine whether and how to digitally sign and encrypt the SOAP message request from an operation invoke from the client application.)

See Using Oracle Web Service Security Policies in Securing WebLogic Web Services for Oracle WebLogic Server for detailed information and examples of using this annotation.

Note:

As is true for all JWS annotations, the @SecurityPolicy annotation cannot be overridden at runtime, which means that the Oracle WSM WS-Policy file you specify at buildtime using the annotation will always be associated with the Web Service. This means, for example, that although you can view the associated Oracle WSM WS-Policy file at runtime using the Administration Console, you cannot delete (unassociate) it. You can, however, associate additional Oracle WSM WS-Policy files using the console; see Configuring Oracle WSM Security Policies in Administration Console in the Securing WebLogic Web Services for Oracle WebLogic Server for detailed instructions.

Attribute

Table 3-39 Attribute of the weblogic.jws.SecurityPolicy JWS Annotation Tag

Name Description Data Type Required?
uri

Specifies the location from which to retrieve the Oracle WSM WS-Policy file.

Use the http: prefix to specify the URL of an Oracle WSM WS-Policy file on the Web.

Use the policy: prefix to specify that the Oracle WSM WS-Policy file is packaged in the Web Service archive file or in a shareable Java EE library of WebLogic Server, as shown in the following example:

@SecurityPolicy(uri= "policy:oracle/wss10_username_token_with_message_protection_server_policy")

String

Yes

Example
@SecurityPolicy(uri=
"policy:oracle/wss10_username_token_with_message_protection_server_policy")

weblogic.wsee.wstx.wsat.Transactional

The following sections describe the annotation in detail.

Description

Target: Class, Method

Specifies whether the annotated class or method runs inside of a web service atomic transaction.

If you specify the @Transactional annotation at the web service class level, the settings apply to all two-way synchronous methods defined by the service endpoint interface. You can override the flow type value at the method level; however, the version must be consistent across the entire transaction.

WebLogic web services enable interoperability with other external transaction processing systems, such as WebSphere, JBoss, Microsoft .NET, and so on, through the support of the following specifications:

Attributes

Table 3-40 Attribute of the weblogic.wsee.wstx.wsat.Transactional Annotation

Name Description Data Type Required?

version

Version of the web services atomic transaction coordination context that is used for web services and clients. For clients, it specifies the version used for outbound messages only. The value specified must be consistent across the entire transaction.

Valid values include WSAT10, WSAT11, WSAT12, and DEFAULT. The DEFAULT value for web services is all three versions (driven by the inbound request); the DEFAULT value for web service clients is WSAT10.

For example:

@Transactional(version=Transactional.Version.WSAT10])

String

No

value

Whether the web service atomic transaction coordination context is passed with the transaction flow. For valid values, see Table 3-41.

String

No

The following table summarizes the valid values for flow type and their meaning on the web service and client. The table also summarizes the valid value combinations when configuring web service atomic transactions for an EJB-style web service that uses the @TransactionAttribute annotation.

Table 3-41 Flow Types Values

Value Web Service Client Web Service Valid EJB @TransactionAttribute Values

NEVER

Do not export transaction coordination context.

Do not import transaction coordination context.

NEVER, NOT_SUPPORTED, REQUIRED, REQUIRES_NEW, SUPPORTS

SUPPORTS (Default)

Export transaction coordination context if transaction is available.

Import transaction coordination context if available in the message.

REQUIRED, SUPPORTS

MANDATORY

Export transaction coordination context. An exception is thrown if there is no active transaction.

Import transaction coordination context. An exception is thrown if there is no active transaction.

MANDATORY, REQUIRED, SUPPORTS

Example
@Transactional(value = Transactional.TransactionFlowType.SUPPORTS,
     version="Transactional.Versino.WSAT12