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:
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:
Create an interface that you want to access on the client. This interface must extend java.rmi.Remote
. See Example 4-1.
Create an implementation class that implements the interface in Step 1.
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.
Compile and bundle the classes in an application.
Deploy the application.
Bind the annotated plain java object in the WebLogic JNDI tree.
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(); }
The following topics provide reference information about WebLogic RMI annotations:
The following sections describe the annotation in more detail.
Provides class-level annotation support for remote objects that specify the remote implementation class.
The following table summarizes the attributes.
Table 4-1 Attributes of the Rmi Annotation
Name | Description | Data Type | Default Value |
---|---|---|---|
|
The |
|
"" |
|
Indicates if the remote object is clusterable. |
|
|
|
Default RMI Method annotation. Can be over-ridden with a method annotation. |
|
|
|
Load Algorithm for clustered remote object. Legal Values are:
Default is |
|
|
|
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. |
|
|
|
A comma-separated list of Interface class names to be treated as remote interface |
|
"" |
The following sections describe the annotation in more detail.
Provides method-level annotation support for remote objects that specify the remote implementation class.
The following table summarizes the attributes.
Table 4-2 Attributes of the RmiMethod Annotation
Name | Description | Data Type | Default Value |
---|---|---|---|
|
If |
|
|
|
Specifies the Work Manager used to schedule remote object requests. |
|
"" |
|
Specifies an Idempotent method. |
|
|
|
Specifies a one-way call. |
|
|
|
Specifies a timeout for a remote call. |
|
0 |
|
Specifies a transactional method. If not, suspend a transaction before making the RMI call and resume the transaction after the call completes. |
|
|
The following sections provide information on WebLogic RMI annotation exception handling:
Clients receive all checked application 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 |
|
WL Thin T3 Client |
|
WLS-IIOP ClientFoot 3 |
or
|
Thin Client |
or
|
Java SE Client |
or
|
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.
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.
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.
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.