All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Foundation |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

*** This class provides Binary Compatibility only, not Source Compatibility ***

## com.sas.net.rmi
Class UnicastRemoteObjectExporter

    com.sas.net.rmi.UnicastRemoteObjectExporter

All Implemented Interfaces:
  RemoteObjectExporterInterface

    public class UnicastRemoteObjectExporter

implements RemoteObjectExporterInterface

Utility class used to export/unexport a unicast remote object to/from the RMI system using `UnicastRemoteObject`.

This utility may be used if either of the following conditions apply:

- a remote object implementation cannot subclass a standard remote object implementation such as `UnicastRemoteObject` because it is required to extend a different superclass.
- one desires to be able to selectively control whether a remote object implementation needs to service remote callers or if it is just being used to service local calls.

## Constructor Examples

This section presents examples that show how to construct a unicast remote object exporter.

- Example 1 : Default socket factories and an anonymous port
- Example 2 : Specified socket factories and an anonymous port
- Example 3 : Specified socket factories and port
- Example 4 : Specified socket factories, port and forcible unexport preference

### Example 1: Construct an Exporter Using Default Socket Factories and an Anonymous Port

The following code example shows how construct an exporter using default RMI socket factories and an anonymous port.

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

     import com.sas.net.rmi.RemoteObjectExporterInterface;
     import com.sas.net.rmi.UnicastRemoteObjectExporter;

     ...

     public SomeRemoteObjectImplementation ()
        implements SomeRemoteInterface {

        private RemoteObjectExporterInterface _rmiExporter;

        public SomeRemoteObjectImplementation ()
           throws RemoteException {

           super();

           ...

           // construct a unicast remote object exporter using:
           // - anonymous port
           // - default RMI socket factories
           // - preference to forcibly unexport the remote object

            boolean isForcibleUnexport = false;

           _rmiExporter = new UnicastRemoteObjectExporter(
              this,                     // the remote object to be exported
              Constants.PORT_ANONYMOUS, // export remote object on an anonymous port
              null,                     // default RMI client socket factory
              null,                     // use default RMI server socket factory
              isForcibleUnexport);      // do not forcibly unexport the remote object

           // export the remote object to the RMI system.
           // a RemoteException will be thrown if the export fails.

           Remote exportedRemoteObject = _rmiExporter.export();

        }

     }

### Example 2: Construct an Exporter Using Specified Socket Factories and an Anonymous Port

The following code example shows how construct an exporter by specifying desired RMI socket factories and an anonymous port.

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

     import com.sas.net.rmi.RemoteObjectExporterInterface;
     import com.sas.net.rmi.UnicastRemoteObjectExporter;
     import com.sas.net.ssl.SSLRMISocketFactories;

     ...

     public SomeRemoteObjectImplementation ()
        implements SomeRemoteInterface {

        private RemoteObjectExporterInterface _rmiExporter;

        public SomeRemoteObjectImplementation ()
           throws RemoteException {

           super();

           ...

           // construct a unicast remote object exporter using:
           // - anonymous port
           // - specified RMI socket factories
           // - preference to forcibly unexport the remote object

           SSLRMISocketFactories sslRMISocketFactories =
              SSLRMISocketFactories.getInstance();
           Class theClass = getClass();

           RMIClientSocketFactory rmiClientSocketFactory =
              sslRMISocketFactories.getRMIClientSocketFactoryForClass(theClass);
           RMIServerSocketFactory rmiServerSocketFactory =
              sslRMISocketFactories.getRMIServerSocketFactoryForClass(theClass);

           boolean isForcibleUnexport = false;

           _rmiExporter = new UnicastRemoteObjectExporter(
              this,                     // the remote object to be exported
              Constants.PORT_ANONYMOUS, // export remote object on an anonymous port
              rmiClientSocketFactory,   // RMI client socket factory
              rmiServerSocketFactory,   // RMI server socket factory
              isForcibleUnexport);      // do not forcibly unexport the remote object

           // export this remote object to the RMI system.
           // RemoteException will be thrown if the export fails.

           Remote exportedRemoteObject = _rmiExporter.export();

        }

     }

### Example 3: Construct an Exporter Using Specified Socket Factories and Port

The following code example shows how construct an exporter by specifying desired RMI socket factories and port.

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

     import com.sas.net.rmi.RemoteObjectExporterInterface;
     import com.sas.net.rmi.UnicastRemoteObjectExporter;
     import com.sas.net.ssl.SSLRMISocketFactories;

     ...

     public SomeRemoteObjectImplementation ()
        implements SomeRemoteInterface {

        private RemoteObjectExporterInterface _rmiExporter;

        public SomeRemoteObjectImplementation ()
           throws RemoteException {

           super();

           // construct a unicast remote object exporter using:
           // - specified port
           // - specified RMI socket factories
           // - preference to forcibly unexport the remote object

           SSLRMISocketFactories sslRMISocketFactories =
              SSLRMISocketFactories.getInstance();
           Class theClass = getClass();

           RMIClientSocketFactory rmiClientSocketFactory =
              sslRMISocketFactories.getRMIClientSocketFactoryForClass(theClass);
           RMIServerSocketFactory rmiServerSocketFactory =
              sslRMISocketFactories.getRMIServerSocketFactoryForClass(theClass);

           int portNumber = 8216;
           boolean isForcibleUnexport = false;

           _rmiExporter = new UnicastRemoteObjectExporter(
              this,                   // the remote object to be exported
              portNumber,             // port on which to export the remote object
              rmiClientSocketFactory, // RMI client socket factory
              rmiServerSocketFactory, // RMI server socket factory
              isForcibleUnexport);    // do not forcibly unexport the remote object

           // export this remote object to the RMI system.
           // RemoteException will be thrown if the export fails.

           Remote exportedRemoteObject = _rmiExporter.export();

        }

     }

### Example 4: Construct an Exporter Using Specified Socket Factories, Port and Forcible Unexport Preference

The following code example shows how construct an exporter by specifying desired RMI socket factories, port, and forcible unexport preference.

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

     import com.sas.net.rmi.RemoteObjectExporterInterface;
     import com.sas.net.rmi.UnicastRemoteObjectExporter;
     import com.sas.net.ssl.SSLRMISocketFactories;

     ...

     public SomeRemoteObjectImplementation ()
        implements SomeRemoteInterface {

        private RemoteObjectExporterInterface _rmiExporter;

        public SomeRemoteObjectImplementation ()
           throws RemoteException {

           super();

           // construct a unicast remote object exporter using:
           // - specified port
           // - specified RMI socket factories
           // - preference to forcibly unexport the remote object

           SSLRMISocketFactories sslRMISocketFactories =
              SSLRMISocketFactories.getInstance();
           Class theClass = getClass();

           RMIClientSocketFactory rmiClientSocketFactory =
              sslRMISocketFactories.getRMIClientSocketFactoryForClass(theClass);
           RMIServerSocketFactory rmiServerSocketFactory =
              sslRMISocketFactories.getRMIServerSocketFactoryForClass(theClass);

           int portNumber = 8216;
           boolean isForcibleUnexport = true;

           _rmiExporter = new UnicastRemoteObjectExporter(
              this,                   // the remote object to be exported
              portNumber,             // port on which to export the remote object
              rmiClientSocketFactory, // RMI client socket factory
              rmiServerSocketFactory, // RMI server socket factory
              isForcibleUnexport);    // do forcibly unexport the remote object

           // export this remote object to the RMI system.
           // RemoteException will be thrown if the export fails.

           Remote exportedRemoteObject = _rmiExporter.export();

        }

     }

## Export/Unexport Examples

This section presents code examples detailing how to export and unexport a remote object.

- Example 5 : Export a remote object
- Example 6 : Unexport a remote object

### Example 5: Export Unicast Remote Object

The following code example shows how to export a remote object.

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

     import com.sas.net.rmi.RemoteObjectExporterInterface;
     import com.sas.net.rmi.UnicastRemoteObjectExporter;
     import com.sas.net.ssl.SSLRMISocketFactories;

     ...

     public SomeRemoteObjectImplementation ()
        implements SomeRemoteInterface {

        private RemoteObjectExporterInterface _rmiExporter;

        public SomeRemoteObjectImplementation ()
           throws RemoteException {

           super();

           // construct a unicast remote object exporter
           // using specified socket factories and an
           // anonymous port

           SSLRMISocketFactories sslRMISocketFactories =
              SSLRMISocketFactories.getInstance();
           Class theClass = getClass();

           RMIClientSocketFactory rmiClientSocketFactory =
              sslRMISocketFactories.getRMIClientSocketFactoryForClass(theClass);
           RMIServerSocketFactory rmiServerSocketFactory =
              sslRMISocketFactories.getRMIServerSocketFactoryForClass(theClass);

           int portNumber = 1099;

           boolean isForcibleUnexport = true;

           _rmiExporter = new UnicastRemoteObjectExporter(
              this,
              portNumber,
              rmiClientSocketFactory,
              rmiServerSocketFactory,
              isForcibleUnexport);

           // export the remote object to the RMI system
           // throws a RemoteException if unable to export the remote object.

           Remote exportedRemoteObject = _rmiExporter.export();

        }

     }

### Example 6: Unexport Unicast Remote Object

The following code example shows how to unexport a remote object.

     import java.rmi.NoSuchObjectException;

     import com.sas.net.rmi.RemoteObjectExporterInterface;
     import com.sas.net.rmi.UnicastRemoteObjectExporter;

     ...

     public SomeRemoteObjectImplementation
        implements SomeRemoteObjectInterface {

        private RemoteObjectExporterInterface _rmiExporter;

        ...

        public destroy ()  {

           ...

           if (_rmiExporter.isExported()) {

              try {
                 // unexport the remote object from the RMI system
                 // note that the remote object will be unexported
                 // forcibly (terminating active and refusing pending calls) if the
                 // preference is to forcibly unexport

                 boolean wasUnexported = _rmiExporter.unexport();

                 if (!wasUnexported) {
                    // if a non-forcible unexport was specified, then
                    // the remote object may still be servicing calls.
                    // forcibly unexport or try again later
                 }

              }
              catch (NoSuchObjectException) {
                 // log an error
              }

           }

        }
     }

Since:
  9.1.3
See Also:
  `UnicastRemoteObject`

Constructor Summary
`UnicastRemoteObjectExporter(java.rmi.Remote remoteObject, int portNumber, java.rmi.server.RMIClientSocketFactory rmiClientSocketFactory, java.rmi.server.RMIServerSocketFactory rmiServerSocketFactory, boolean isForcibleUnexport)` Constructs an instance of an exporter which may be used to export the specified remote object to the RMI system on a particular port using the specified client and server socket factories and the preference to forcibly unexport the remote object.

Method Summary
`protected java.rmi.Remote` | `exportObject(java.rmi.Remote remoteObject, int portNumber, java.rmi.server.RMIClientSocketFactory rmiClientSocketFactory, java.rmi.server.RMIServerSocketFactory rmiServerSocketFactory)` Exports the remote object returning the remote object's stub.
`protected boolean` | `unexportObject(java.rmi.Remote exportedRemoteObjectStub, boolean isForcibleUnexport)` Unexports the exported remote object's stub from the RMI system.

Methods inherited from class com.sas.net.rmi.AbstractRemoteObjectExporter
`exportObject, getExportedRemoteObjectStub, getPortNumber, getRemotableObject, getRMIClientSocketFactory, getRMIServerSocketFactory, isExported, isForcibleUnexport, setIsForcibleUnexport, unexportObject`

Methods inherited from interface com.sas.net.rmi.RemoteObjectExporterInterface
`exportObject, getExportedRemoteObjectStub, isExported, unexportObject`

Constructor Detail

### UnicastRemoteObjectExporter

    public UnicastRemoteObjectExporter(java.rmi.Remote remoteObject,
                                       int portNumber,
                                       java.rmi.server.RMIClientSocketFactory rmiClientSocketFactory,
                                       java.rmi.server.RMIServerSocketFactory rmiServerSocketFactory,
                                       boolean isForcibleUnexport)
                                throws java.lang.IllegalArgumentException

  Constructs an instance of an exporter which may be used to export the specified remote object to the RMI system on a particular port using the specified client and server socket factories and the preference to forcibly unexport the remote object.

  Parameters:
    `remoteObject` - The remote object that may be exported to the RMI system to create a remote object stub.
    `portNumber` - Port on which the object should be exported. Specify `Constants.PORT_ANONYMOUS` to designate an anonymous port or a value greater than `0` to designate a well-known port.
    `rmiClientSocketFactory` - The client-side RMI socket factory is used to create sockets to make calls to the remote object or `null` if using the default.
    `rmiServerSocketFactory` - The server-side RMI socket factory is used to create sockets to receive remote calls or `null` if using the default.
    `isForcibleUnexport` - Specify `true` if the remote object should be unexported without regard to whether there are any active or pending remote calls or `false` if the remote object should not be unexported if there are active or pending calls.
  Throws:
    `java.lang.IllegalArgumentException` - if an invalid remote object

Method Detail

### exportObject

    protected final java.rmi.Remote exportObject(java.rmi.Remote remoteObject,
                                                 int portNumber,
                                                 java.rmi.server.RMIClientSocketFactory rmiClientSocketFactory,
                                                 java.rmi.server.RMIServerSocketFactory rmiServerSocketFactory)
                                          throws java.rmi.RemoteException

  Exports the remote object returning the remote object's stub.

  This method is called by `AbstractRemoteObjectExporter.exportObject()` to export a unicast remote object stub. This method provides the concrete implementation of a template method used to unexport a remote object stub using `UnicastRemoteObject.exportObject(Remote, int, RMIClientSocketFactory, RMIServerSocketFactory)` .

  Specified by:
    `exportObject` in class `AbstractRemoteObjectExporter`
  Parameters:
    `remoteObject` - The remote object that may be exported to the RMI system to create a remote object stub. Ensure that the remote object implementation correctly implements hashCode, equals, and toString methods to ensure correct behavior by the remote object.
    `portNumber` - Port on which the object should be exported. Specify `Constants.PORT_ANONYMOUS` to designate an anonymous port or a value greater than `0` to designate a well-known port.
    `rmiClientSocketFactory` - The client-side RMI socket factory is used to create sockets to make calls to the remote object or `null` if using the default.
    `rmiServerSocketFactory` - The server-side RMI socket factory is used to create sockets to receive remote calls or `null` if using the default.
  Returns:
    Exported remote object's stub. The stub will always be non-`null`.
  Throws:
    `java.rmi.RemoteException` - if unable to unexport the remote object.

### unexportObject

    protected final boolean unexportObject(java.rmi.Remote exportedRemoteObjectStub,
                                           boolean isForcibleUnexport)
                                    throws java.rmi.NoSuchObjectException

  Unexports the exported remote object's stub from the RMI system.

  This method is called by `AbstractRemoteObjectExporter.unexportObject()` to unexport a unicast remote object stub previously exported using `AbstractRemoteObjectExporter.exportObject()`. This method provides the concrete implementation of a template method used to unexport a remote object stub using `UnicastRemoteObject.unexportObject(Remote, boolean)`.

  Specified by:
    `unexportObject` in class `AbstractRemoteObjectExporter`
  Parameters:
    `exportedRemoteObjectStub` - The remote object's stub which is to be removed from the RMI system. This is the stub which was obtained from the `AbstractRemoteObjectExporter.exportObject()` call.
    `isForcibleUnexport` - `true` if the remote object's stub should be forcibly removed from the RMI system without regard to whether there are any active or pending calls. Specify `false` if the stub should not be unexported if there are active or pending calls.
  Returns:
    `true` if the exported remote object's stub was successfully unexported from the RMI system.
  Throws:
    `java.rmi.NoSuchObjectException` - if unable to unexport the remote object.

*** This class provides Binary Compatibility only, not Source Compatibility ***

All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Foundation |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009 SAS Institute Inc. All Rights Reserved.