[AIX Solaris HP-UX Linux Windows][z/OS]

Using PassByReference optimization in SCA applications (deprecated)

Support exists for the @AllowsPassByReference annotation, which can be used to bypass marshaling and unmarshaling when a client invokes a service located in the same JVM over a remote interface.

About this task

Typically, a performance intensive aspect of service invocations is data marshaling and unmarshaling. Though invocation over a local interface always results in pass-by-reference semantics so that no data is copied, an invocation over a remotable interface entails pass-by-value semantics, which typically results in copying of the data which can be expensive.

The SCA default binding provides the @AllowsPassByReference as an optimization that you can use on your service implementation at the class level or at the individual method level.

In placing the @AllowsPassByReference annotation on the service implementation class or methods, the implementor agrees not to modify the data in a way that would violate the pass-by-value semantics. This allows both client and service to assume they are working with their own copy of the data even though the runtime environment has optimized to not perform the actual data serialization and deserialization, to save this expense.

Parameters, return types, and business exceptions are passed by reference if the service implementation class has the @AllowsPassByReference annotation defined at the class level or individual method level.

More specifically, the PassByReference optimization is performed when all of the following are true:
  • Client and service have been targeted to the same JVM.
  • The invocation is over the default binding.
  • @AllowsPassByReference is present. Either the service implementation is a Java™ implementation with an appropriate @AllowsPassByReference annotation, or a composite implementation, ultimately recursively implemented in terms of such an @AllowsPassByReference-annotated Java implementation.
  • All input, output, and exception types have the same package-qualified class names and can be loaded by a class loader common to or shared by both client and service.
  • Both client and service are part of the same business-level application.

    This requirement applies to OSOA SCA applications. For OSOA SCA applications, both client and service must be part of the same business-level application. This requirement does not apply to OASIS SCA applications.

Procedure

  1. To enable PassByReference optimization for SCA applications, ensure all classes that you want to optimize are loaded by the same class loader.
    Use the SCA contribution import and export support.
  2. Create a Java archive (JAR) file that contains all classes that are loaded by the same class loader during both client and service execution.
  3. Add an sca-contribution.xml file to the META-INF directory in the JAR.
    See the OSOA Assembly specification for information on sca-contribution.xml. The contribution definition must contain an export.java statement that exports all packages contained in the JAR that are accessed by either the client or service JAR file. For example:
    <contribution xmlns="https://www.osoa.org/xmlns/sca/1.0"
    targetNamespace="http://test.sca.scafp/pbr/shared/java">
    <export.java package="com.ibm.sample.interface"/>
    <export.java package="com.ibm.sample.types"/>
</contribution>
    If the client and service JAR files are not already using an sca-contribution.xml file, update these files to use a contribution definition that imports the packages that are exported by the shared library. For example, the contribution files for the client and service that access the previous shared contribution might look like this:
    Client:
<contribution xmlns="https://www.osoa.org/xmlns/sca/1.0"
    targetNamespace="http://test.sca.scafp/pbr/shared"
    xmlns:pbr="http://test.sca.scafp/pbr/shared">
    <deployable composite="pbr:PassByRef.SharedClient"/>
    <import.java package="com.ibm.sample.interface"/>
    <import.java package="com.ibm.sample.types"/>
</contribution>

Service:
<contribution xmlns="https://www.osoa.org/xmlns/sca/1.0"
    targetNamespace="http://test.sca.scafp/pbr/shared"
    xmlns:pbrsh="http://test.sca.scafp/pbr/shared">
    <deployable composite="pbrsh:PassByRef.SharedService"/>
    <import.java package="com.ibm.sample.interface"/>
    <import.java package="com.ibm.sample.types"/>
</contribution>
  4. Deploy the SCA application

    Add the client, service, and shared contributions as an asset into the WebSphere® repository. This can occur in any order, however you must add the shared contribution as an asset before you can add either the client or service asset as a composition unit to a business-level application. Only the client and service assets need to be added as composition units to your business-level applications. During the add composition unit operation for both the client and the service, the shared asset is automatically added to the business-level application as a shared library.

    Clients that are deployed outside of a business-level application cannot use the PassByReference optimization to invoke SCA services deployed inside a business-level application. For example, a user-created web application archive (WAR) file using the default binding cannot be installed into a business-level application, and therefore a WAR-hosted client might not participate in the PassByReference optimization. The PassByReference optimization is supported only between JAR files.

    For OSOA SCA applications, you must install both service JAR files in the same business-level application.

    For OASIS SCA applications, the JAR files can be in separate business-level applications.

Results

You have enabled PassByReference optimization for SCA applications.