Fusion Middleware Documentation
Advanced Search


Developing RMI Applications for Oracle WebLogic Server
Close Window

Table of Contents

Show All | Collapse

4 Using WebLogic RMI Annotations

This chapter describes the WebLogic RMI annotations that provide remote access to plain java objects.

WebLogic RMI provides a rich descriptor framework to associate various security, transactions, clustering, and timeout attributes to a remote class and its methods. These attributes can be specified as annotations in plain java implementation classes with non-remote interfaces when the remote object implementation is bound to a WebLogic JNDI tree. See weblogic.rmi.annotation in Java API Reference for Oracle WebLogic Server.

This chapter includes the following sections:

Introduction to WebLogic RMI Annotations

WebLogic RMI provides annotation support that can be embedded inside a remote java object and simplifies development by allowing you to avoid running weblogic.rmic tool on the compiled class.

To make a plain java object remotely accessible, do the following:

  1. Create an interface that you want to access on the client. This interface must extend java.rmi.Remote. See Example 4-1.

  2. Create an implementation class that implements the interface in Step 1.

  3. Add the desired annotation @Rmi or @RmiMethod to the implementation class added in Step 2. The annotations need to be provided on the implementation class and methods, not on the interfaces.

  4. Compile and bundle the classes in an application.

  5. Deploy the application.

  6. Bind the annotated plain java object in the WebLogic JNDI tree.

  7. A client looks up the plain java object as remote object from the WebLogic JNDI tree and narrows it to the plain interfaces annotated as remote interfaces. The corresponding stub is either generated on the client, downloaded, or pre-generated using the WebLogic RMI compiler and made available on the client.

    Note:

    Do not use the WebLogic RMIC option to generate stubs and skeletons based on the Sun RMI compiler.

Example 4-1 Example RMI Annotation

package myrmi.example;

import java.rmi.RemoteException;
import java.util.concurrent.Future;
import java.util.concurrent.FutureTask;

import weblogic.rmi.annotation.Rmi;
import weblogic.rmi.annotation.RmiMethod;

@Rmi(remoteInterfaces={MyRemoteInterface.class})
public class RmiMethodAnnotations implements MyRemoteInterface{
  public RmiMethodAnnotations() {
  }
 
  public int getIndex() throws RemoteException {
    return 0;
  }

  @RmiMethod(asynchronousResult=true)
  public Future<String> ejbAsynchronousSayHello(String name) {
    return new FutureTask(new MyRunnable(), new Object());
  }

  class MyRunnable implements Runnable {

    public void run() {
    }
  }
}

This allows the WebLogic RMI layer to treat the RmiMethodAnnotations object as remote object when it is bound to the WLS JNDI tree.

Example 4-2 provides an example of code that implements the same methods without using annotations.

Example 4-2 Example RMI without Annotations

package myrmi.example;

import java.rmi.Remote;
import java.rmi.RemoteException;

import java.util.concurrent.Future;

public interface MyRemoteInterface extends Remote {

  int getIndex() throws RemoteException;

  public Future<String> ejbAsynchronousSayHello(String name);

  public String sayBye();

}

Annotations for WebLogic RMI

The following topics provide reference information about WebLogic RMI annotations:

Rmi

The following sections describe the annotation in more detail.

Description

Provides class-level annotation support for remote objects that specify the remote implementation class.

See weblogic.rmi.annotation.Rmi.

Attributes

The following table summarizes the attributes.

Table 4-1 Attributes of the Rmi Annotation

Name Description Data Type Default Value

callRouterClassname

The CallRouter class that is called before each invocation with the parameters of the call and it returns the name server to which the call should be routed. Parameter-based routing allows to provide a more fine-grained load balancing behavior.

String

""

clusterable

Indicates if the remote object is clusterable.

boolean

false

defaultRMIMethodParams

Default RMI Method annotation. Can be over-ridden with a method annotation.

RmiMethod

@weblogic.rmi.annotation.RmiMethod

loadAlgorithm

Load Algorithm for clustered remote object. Legal Values are:

  • RANDOM

  • ROUND_ROBIN

  • WEIGHT_BASED

  • SERVER_AFFINITY

  • ROUND_ROBIN_AFFINITY

  • RANDOM_AFFINITY

  • WEIGHT_BASED_AFFINITY

  • DEFAULT

Default is ROUND_ROBIN.

LoadAlgorithmType

weblogic.rmi.annotation.LoadAlgorithmType.DEFAULT

stickToFirstServer

Enables sticky load balancing. The server chosen for servicing the first request is used for all subsequent requests. Only used for a clusterable remote object.

boolean

false

remoteInterfaces

A comma-separated list of Interface class names to be treated as remote interface

Class

""


RmiMethod

The following sections describe the annotation in more detail.

Description

Provides method-level annotation support for remote objects that specify the remote implementation class.

See weblogic.rmi.annotation.RmiMethod.

Attributes

The following table summarizes the attributes.

Table 4-2 Attributes of the RmiMethod Annotation

Name Description Data Type Default Value

asynchronousResult

If true, marks a method for asynchronous processing. Typically when a method is invoked, the result is returned upon the completion of the method execution. When asynchronousResult=true, the return type of the method can be either void or a Future object. If the type is a Future object, it can be polled to see when the result is available. If the type is a void, the method is treated as an asynchronous one-way call.

boolean

false

dispatchPolicy

Specifies the Work Manager used to schedule remote object requests.

String

""

idempotent

Specifies an Idempotent method.

boolean

false

oneway

Specifies a one-way call.

boolean

false

timeout

Specifies a timeout for a remote call.

int

0

transactional

Specifies a transactional method. If not, suspend a transaction before making the RMI call and resume the transaction after the call completes.

boolean

false


Exception Handling

The following sections provide information on WebLogic RMI annotation exception handling:

Application Exceptions

Clients receive all checked application exceptions.

System Exceptions

Client receive all the errors and runtime exceptions encountered during remote method invocation.

Remote exceptions are handled as follows:

  • Checked exceptions are thrown directly to a client.

  • Unchecked exceptions are wrapped in a RuntimeException and then thrown to the client.

  • Generated EJB 3.0 objects annotate the remoteExceptionWrapper to be EJBException for all EJB methods. Clients then receive all remote exceptions wrapped in EJBException.

You can specify the remoteExceptionWrapper annotation for an entire implementation class or for a particular method which wraps all remote exceptions in the specified runtime exception before throwing it back to the client. If the remoteExceptionWrapper annotation is not specified then the remote exceptions are wrapped as shown in Table 4-3.

Table 4-3 Exception Wrapping in WebLogic Clients

Client Exception Wrapping

WL Full Client

RemoteRuntimeExceptionFoot 1  wraps RemoteException

WL Thin T3 Client

RemoteRuntimeExceptionFoot 2  wraps RemoteException

WLS-IIOP ClientFoot 3 

RemoteRuntimeException wraps java.rmi.ServerException wraps RemoteException

or

RemoteRuntimeException wraps RemoteException

Thin Client

java.lang.RuntimeException wraps ServerException wraps RemoteException

or

RuntimeException wraps RemoteException

Java SE Client

java.lang.RuntimeException wraps ServerException wraps RemoteException

or

RuntimeException wraps RemoteException


Footnote 1 weblogic.rmi.extensions.RemoteRuntimeException is a sub-class of RuntimeException

Footnote 2 weblogic.rmi.extensions.RemoteRuntimeException is a sub-class of RuntimeException

Footnote 3 The existing T3 protocol layer doesn't always wraps the RemoteException as java.rmi.ServerException but the IIOP protocol always does it on the Server.

Cluster Failover

Clustered stubs automatically handle the failover of a remote call to another node in the cluster based on the type of exception received. Wrapping remote exceptions, such as RuntimeException, in the stub does not change the failover behavior for a remote object.

RMI Callback Objects

Passing a callback object with an annotated remote object requires the callback remote object to extend java.rmi.Remote interface.

Note:

Some client types can not support callback objects because they do not have access to WebLogic classes. For example, the Java SE client.

Annotation and WebLogic RMI Descriptor Merging

Annotations specified in the implementation class cannot be over-ridden on the server. You must ensure that the right set of descriptor values are used by merging the application descriptors and deployment plans.