# Using Servant Activators

## What is a Servant Activator?

When creating a new POA, the application developer may declare specific policy choices for the new POA and provide a different adapter activator and servant manager (these are callback objects used by the POA to activate POAs on demand and activate servants). Creating new POAs also allows the application developer to partition the name space of objects, as Object Ids are interpreted relative to a POA. Finally, by creating new POAs, the developer can independently control request processing for multiple sets of objects.

A Servant Activator is a type of Servant Manager. Servant Managers are optional. You would use a servant manager to allow the POA to activate servants on demand when a request for an inactive object is received. If your server loads all objects when it starts up, you do not need a servant manager.

A servant manager is a callback object that the application developer can associate with a POA. The ORB will invoke operations on servant managers to activate servants on demand, and to deactivate servants. Servant managers are responsible for managing the association of an object reference (as characterized by its Object Id value) with a particular servant, and for determining whether an object reference exists or not. Each servant manager type contains two operations, the first called to find and return a servant and the second to deactivate a servant. The operations differ according to the amount of information usable for their situation.

To use servant managers, the `USE_SERVANT_MANAGER` policy must be set. Once set, the type of servant manager used in a particular situation depends on other policies in the POA. The two types of servant managers are:

- `ServantActivator`

  When the POA has the `RETAIN` policy, it uses servant managers that are `ServantActivators`. A `ServantActivator` always results in an entry in the Active Object Map. The servant is then used until it is deactivated. A servant can be deactivated by destroying the POA, the POA Manager, or the ORB, or by an explicit `deactivate` call.

  - This document includes an example that uses Servant Activators, see An Example Using Servant Activators.

- `ServantLocator`

  When the POA has the `NON_RETAIN` policy, it uses servant managers that are `ServantLocators`. Because the POA knows that the servant returned by this servant manager will be used only for a single request, it can supply extra information to the servant manager's operations and the servant manager's pair of operations may be able to cooperate to do something different than a `ServantActivator`. When the POA uses the `ServantLocator` interface, immediately after performing the operation invocation on the servant returned by preinvoke, the POA will invoke postinvoke on the servant manager, passing the ObjectId value and the Servant value as parameters (among others). This feature may be used to force every request for objects associated with a POA to be mediated by the servant manager.

  - For an example that uses Servant Locators see Using Servant Locators.

# An Example Using Servant Activators

**In progress, please check back for updates!

The following example code shows an application that uses Servant Activators to enable the POA to activate transient objects. This application builds on the "Hello World" example. The following files are included for your information:

- `Client.java`
- `Server.java`
- `Hello.idl`
- `HelloImpl.java`
- `Makefile`
- `runSample`

## Client.java

    import org.omg.CORBA.ORB;
    import org.omg.CosNaming.*;

    public class Client {
        public Client(String[] args) {
            try {
        	    ORB orb = ORB.init(args, System.getProperties());
    	    NamingContext rootContext = NamingContextHelper.narrow(
                    orb.resolve_initial_references("NameService"));

                // Resolves for remote object reference of HelloServer
    	    NameComponent name[] = {new NameComponent("HelloServer", "")};
    	    Hello helloRef = HelloHelper.narrow(rootContext.resolve(name));
                System.out.println("\nClient: Obtained the remote object " +
                                   "reference");

                // Invokes the remote sayHello() method
                System.out.println("Client: Invoking the remote operation ...");
    	    System.out.println(helloRef.sayHello());
            } catch (Exception e) {
                System.err.println("\nClient: Caught exception - " + e);
                e.printStackTrace();
            }
        }

        public static void main(String [] args) {
    	Client servantActivatorClient = new Client(args);
        }
    }

## Server.java

    import org.omg.CORBA.*;
    import org.omg.PortableServer.*;
    import org.omg.CosNaming.*;

    public class Server {
        public Server(String[] args) {
            try {
                ORB orb = ORB.init(args, System.getProperties());
                POA rootPoa = (POA) orb.resolve_initial_references("RootPOA");
                rootPoa.the_POAManager().activate();
                System.out.println("\nServer: Obtained from ORB and activated " +
                                   "the " + rootPoa.the_name());

                Policy poaPolicy[] = new Policy[2];
                poaPolicy[0] = rootPoa.create_servant_retention_policy(
                    ServantRetentionPolicyValue.RETAIN);
                poaPolicy[1] = rootPoa.create_request_processing_policy(
                    RequestProcessingPolicyValue.USE_SERVANT_MANAGER);
                System.out.println("Server: Set POA policy as RETAIN and " +
                                   "USE_SERVANT_MANAGER");

                POA poa1 = rootPoa.create_POA("HelloPoa", null, poaPolicy);
                poa1.the_POAManager().activate();
                System.out.println("Server: Created and activated child POA " +
                                   "\"" + poa1.the_name() + "\"");

                poa1.set_servant_manager(new PoaServantActivator());
                System.out.println("Server: Associated the servant manager of " +
                                   "type servant activator with \"" +
                                   poa1.the_name() + "\"");

                // This create_reference operation does not cause an activation,
                // the resulting object reference will be exported and passed to
                // client, so that subsequent requests on the reference will cause
                // the appropriate servant manager to be invoked
                org.omg.CORBA.Object objectRef = poa1.create_reference(
                    HelloHelper.id());
                System.out.println("Server: Created a CORBA object reference " +
                                   "from id \"" + HelloHelper.id() + "\"");

                NamingContext rootContext = NamingContextHelper.narrow(
                    orb.resolve_initial_references("NameService"));
                NameComponent name[] = {new NameComponent("HelloServer", "")};
                rootContext.rebind(name, objectRef);
                System.out.println("Server: Exported the CORBA object reference " +
                                   "to NameService");

                System.out.println("Server: Ready and waiting for requests ...");
                orb.run();
            } catch (Exception e) {
                System.err.println("\nServer: Caught exception - " + e);
                e.printStackTrace();
            }
        }

        public static void main(String [] args) {
            Server serverServantActivator = new Server(args) ;
        }
    }

    class PoaServantActivator extends LocalObject implements ServantActivator {
        // The incarnate operation is invoked by the POA whenever the POA receives
        // a request for an object that is not currently active, assuming the POA
        // has the RETAIN and USE_SERVANT_MANAGER policies
        public Servant incarnate(byte[] oid, POA adapter) throws ForwardRequest {
            try {
                HelloImpl servantObj = new HelloImpl();
                System.out.println("PoaServantActivator.incarnate(): Created \"" +
                                   servantObj.getClass().getName() + "\" " +
                                   "servant object for \"" + adapter.the_name() +
                                   "\"");
                return servantObj;
            } catch (Exception e) {
                System.err.println("incarnate: Caught exception - " + e);
            }
            return null;
        }

        public void etherealize(byte[] oid, POA adapter, Servant serv,
                                boolean cleanup_in_progress,
                                boolean remaining_activations) {
        }
    }

## Hello.idl

    interface Hello {
        string sayHello();
    };

## HelloImpl.java

    public class HelloImpl extends HelloPOA {

        public String sayHello() {
            return "Hello :)";
        }

    }

## Makefile

    IDLJ=${JAVA_HOME}/bin/idlj
    JAVAC=${JAVA_HOME}/bin/javac
    JAVA=${JAVA_HOME}/bin/java

    CLASSFILES=./classes_dir
    IDLJFLAGS=-fall -verbose -td ${CLASSFILES}
    JFLAGS=-g -d $(CLASSFILES) -classpath $(CLASSFILES)
    JAVAFLAGS=-cp $(CLASSFILES) -Dorg.omg.CORBA.ORBInitialHost=localhost \
              -Dorg.omg.CORBA.ORBInitialPort=1950
    ORBD_FLAGS=-port 1949 -ORBInitialHost ${SERVER_HOSTNAME} \
               -ORBInitialPort 1950 -ORBDebug
    ORBD=${JAVA_HOME}/bin/orbd $(ORBD_FLAGS) orbd

    client = Client.java

    server = HelloImpl.java \
    	 Server.java

    all: clean build run

    clean:
    	@echo ""
    	@echo "*** Clean up old files and directories ***"
    	-$(RM) $(CLASSFILES)
    	-$(RM) ./orb.db
    	-$(RM) ./kill_started_processes.sh

    build: stubs client_server

    stubs: Hello.idl
    	@echo ""
    	@echo "*** Generate stubs and helpers ***"
    	@-$(MKDIR) $(CLASSFILES)
    	$(IDLJ) $(IDLJFLAGS) Hello.idl

    client_server: $(client) $(server)
    	@echo ""
    	@echo "*** Compile client, server and implementation ***"
    	$(JAVAC) $(JFLAGS) $(client) $(server)

    run: run_orbd run_server run_client terminate_servers

    run_orbd:
    	@echo ""
    	@echo "*** Start the orbd ***"
    	$(ORBD) & \
    	echo "kill -9 $$!" > ./kill_started_processes.sh; \
    	if [ $(OS) = "WinNT" ] ; then \
    	    tpid=`ps -o pid,ppid,comm | grep $$! | grep -v "sh" | cut -c1-6` ; \
    	    echo "kill -9 $$tpid" >> ./kill_started_processes.sh ; \
    	fi ; \
    	$(SLEEP) $(SLEEP_LONG)

    run_server: run_orbd
    	@echo ""
    	@echo "*** Start the Server ***"
    	$(JAVA) $(JAVAFLAGS) Server & \
    	echo "kill -9 $$!" >> ./kill_started_processes.sh; \
    	if [ $(OS) = "WinNT" ] ; then \
    	tpid=`ps -o pid,ppid,comm | grep $$! | grep -v "sh" | cut -c1-6` ; \
    	echo "kill -9 $$tpid" >> ./kill_started_processes.sh ; \
    	fi ; \
    	$(SLEEP) $(SLEEP_NORMAL)

    run_client:
    	@echo ""
    	@echo "*** Start the Client ***"
    	$(JAVA) $(JAVAFLAGS) Client

    terminate_servers:
    	@echo ""
    	@echo "*** Terminate the Server and orbd ***"
    	@$(SLEEP) $(SLEEP_SHORT)
    	@if [ -f ./kill_started_processes.sh ]; then \
    		$(CHMOD) u+x ./kill_started_processes.sh; \
    		./kill_started_processes.sh; \
    		$(SLEEP) $(SLEEP_SHORT) ; \
    	fi

## runSample

    #!/bin/ksh

    if [ `uname` = "SunOS" ] ; then
        OS="Solaris_sparc"
        JAVA_HOME=/path_to_your_java_installation
        SEP=:
        SLEEP=/bin/sleep
        RM="/bin/rm -rf"
        CHMOD=/bin/chmod
        MKDIR=/bin/mkdir
        SLEEP_SHORT=2
        SLEEP_NORMAL=5
        SLEEP_LONG=7
    elif [ `uname` = "Windows_NT" ] ; then
        OS="WinNT"
        if [ ! -d "y:/path_to_your_java_installation" ] ; then
            echo; echo "Please map drive y: to \\\\\your_Java_drive before runSample"
            exit 1
        fi
        JAVA_HOME="y:/path_to_your_java_installation"
        SEP=";"
        SLEEP=sleep
        RM="rm -rf"
        CHMOD=chmod
        MKDIR="mkdir -p"
        SLEEP_SHORT=5
        SLEEP_NORMAL=10
        SLEEP_LONG=15
    fi

    while [ $# -gt 0 ] ; do
       case $1 in
       -host ) SERVER_HOSTNAME=$2 ;
               shift;;
       * ) TARGET=$* ;
           break ;;
       esac
       shift
    done

    DEFAULT_HOSTNAME=localhost
    SERVER_HOSTNAME=${HOSTNAME-$DEFAULT_HOSTNAME}

    make ${TARGET} \
       "OS=${OS}" \
       "JAVA_HOME=${JAVA_HOME}" \
       "SERVER_HOSTNAME=${SERVER_HOSTNAME}" \
       "SLEEP=${SLEEP}" \
       "RM=${RM}" \
       "CHMOD=${CHMOD}" \
       "MKDIR=${MKDIR}" \
       "SLEEP_SHORT=${SLEEP_SHORT}" \
       "SLEEP_NORMAL=${SLEEP_NORMAL}" \
       "SLEEP_LONG=${SLEEP_LONG}"

## Running the Example Servant Activator Example

To run this example,

1. Create the files using the code shown above.
2. Run the example as shown in `runSample`.

You will see output generated to the terminal window similar to that below:

    *** Clean up old files and directories ***
    /bin/rm -rf ./classes_dir
    /bin/rm -rf ./orb.db
    /bin/rm -rf ./kill_started_processes.sh

    *** Generate stubs and helpers ***
    /path_to_your_java_installation/bin/idlj -fall -verbose -td ./classes_dir Hello.idl
    Parsing Hello.idl
    done  - Hello.idl

    Generating Hello
    done   -   Hello

    *** Compile client, server and implementation ***
    /path_to_your_java_installation/bin/javac -g -d ./classes_dir -classpath
    ./classes_dir Client.java HelloImpl.java Server.java

    *** Start the orbd ***
    /path_to_your_java_installation/bin/orbd -port 1949 -ORBInitialHost localhost
    -ORBInitialPort 1950 -ORBDebug orbd & \
    echo "kill -9 $!" > ./kill_started_processes.sh; \
    if [ Solaris_sparc = "WinNT" ] ; then \
        tpid=`ps -o pid,ppid,comm | grep $! | grep -v "sh" | cut -c1-6` ; \
        echo "kill -9 $tpid" >> ./kill_started_processes.sh ; \
    fi ; \
    /bin/sleep 7
    ORBD begins initialization.
    ORBD is ready.
    ORBD serverid: 1
    activation dbdir: /path_to_your_sample_file/ServantActivator/./orb.db
    activation port: 1949
    activation Server Polling Time: 1000 milli-seconds
    activation Server Startup Delay: 1000 milli-seconds

    *** Start the Server ***
    /path_to_your_java_installation/bin/java -cp ./classes_dir
    -Dorg.omg.CORBA.ORBInitialHost=localhost -Dorg.omg.CORBA.ORBInitialPort=1950 Server & \
    echo "kill -9 $!" >> ./kill_started_processes.sh; \
    if [ Solaris_sparc = "WinNT" ] ; then \
    tpid=`ps -o pid,ppid,comm | grep $! | grep -v "sh" | cut -c1-6` ; \
    echo "kill -9 $tpid" >> ./kill_started_processes.sh ; \
    fi ; \
    /bin/sleep 5

    Server: Obtained from ORB and activated the RootPOA
    Server: Set POA policy as RETAIN and USE_SERVANT_MANAGER
    Server: Created and activated child POA "HelloPoa"
    Server: Associated the servant manager of type servant activator with "HelloPoa"
    Server: Created a CORBA object reference from id "IDL:Hello:1.0"
    Server: Exported the CORBA object reference to NameService
    Server: Ready and waiting for requests ...

    *** Start the Client ***
    /path_to_your_java_installation/bin/java -cp ./classes_dir
    -Dorg.omg.CORBA.ORBInitialHost=localhost -Dorg.omg.CORBA.ORBInitialPort=1950 Client

    Client: Obtained the remote object reference
    Client: Invoking the remote operation ...
    PoaServantActivator.incarnate(): Created "HelloImpl" servant object for "HelloPoa"
    Hello :)

    *** Terminate the Server and orbd ***

# Further Information

For more information on Servant Activators, see the section on Servant Managers, in section 11.3.4 of the CORBA 2.3.1 Specification.

Java IDL Home