Back to the overview. Working with SimpleRootBC *
  • Working with SimpleRootBC
  • Setting up a server to use SimpleRootBC
  • Format of the root object registration file
  • Format of the context.cfg file.
  • Building Root MOs
  • Working with SimpleRootBC

    SimpleRootBC provides a facility for activating the resources of a server. It allows the top level (root) resources and resource managers to be registered in a simple way and then provides automatic activation of these resources. It also provides coordination and control over resource sharing within a single address-space by introducing the notion of an activation space. Activation spaces are named and sharable. Within one activation space repeated resolution of a name to an object will always return the same object activation. Across activation spaces resolution of the same name will return separate activations of the object. Once a root object is activated in a activation space it will remain active until the activation space is deactivated by an explicit call.

    To use the SimpleRootBC facility there are a few steps you need to take as follows.

    1. Prepare your root objects so that they can be managed by SimpleRootBC. The details of how to do this are given in a separate section below.

    2. Name your activation space and register your root objects in it. This consists of defining a directory that is reachable from your server. The name of this directory is the name of your activation space. The name must be one that can be passed to a Java File class in the execution context that SimpleRootBC is running. It can be relative or absolute. The SimpleRootBC must at least have read access to this directory. If you want your root objects to be able to save changes to their state then SimpleRootBC must have write access to this directory. This directory is called your base directory.

      Then create one file in your base directory for each root object that you want to be accessible from your server. The file's name will be the name of your object and the file's content must provide the full Java class name for your object and a serialization of any initial state you want for your object when it is activated. The format of this file is discussed in a separate section below.

    3. Construct one file called "context.cfg" that contains the dependent context for your application. The format of this file is discussed below. This file also goes in your base directory. You need to provide this file even if it is empty.

    You are now ready to use your objects depending on the programming model you are following. If your are writing a Java applet or application that will use our IIOP servlet support to access your objects running in a web server, then there is a standard servlet template that we provide that you modifiy to add the name for your activation space and it will provide (via SimpleRootBC and IIOP support) access to the objects you have registered into your activation space. The next section discusses the servlet template.

    Setting up a server to use SimpleRootBC

    See the general Bojangles tutorial for more information on this.

    Format of the root object registration file

    The basic format of a root object registration file is:

      item ; item; ... ;
    
    where each item is the ASCII rendering of one value that will be read using a InputEDStream in your object's internalizeFromStream method. Leading and trailing white space around each item is ignored. Strings and chars are not quoted. Backslash quoting is supported. For example:
          -789 ; 234.34;   Account update for June;
    
    Defines an integer, -789; a float (or double), 234.34; and a String, "Account update for June". A more complex example is:
         -786; \u2345; \ \ Foo  ; ;
    
    which defines an integer, -786; a char, \u2345; a String, " Foo"; and a String, "". The first item must be the Java class name (e.g., myPackage.myClass) that will be used to create an instance of your object. The rest of the items are whatever you need to initialize your object. You will write a method like the following.
    public void internalizeFromStream(InputEDStream in) {
      super.internalizeFromStream(in);
      field1 = in.readInt();
      field2 = in.readFloat();
      field3 = in.readString();
    }
    
    This would read in an int, a float, and a String. And assign them to your fields.

    Format of the context.cfg file

    The context.cfg file needs one entry for each element of the dependent context that will be passed by the root to each of the root level objects. If these objects are BaseCollections then they will pass this dependent context on to each of their objects and so on.

    Each entry in this file is of the from:

          { name; type; data; }
    
    Where:
  • name is the name to be bound to the data. This is the key that will be used with resolve to look up the data in the dependent context.
  • type is the type of the entry, and
  • data is different for each of the types of entries. The following entry types are supported.
  • string
    These entries allow strings to be added to the dependent context. They have the form:
    { name; string ; string_value; }
    E.g., { UserClassName ; string; COM.ibm.jaws.models.trs.User; }
    
    Manageable
    These entries allow Manageable objects to be added to the dependent context. They have the form:
    { name; manageable; manageables_class; manageables_essential_data; }
    E.g., { CacheManager ; manageable; COM.ibm.jaws.models.trs.User; }
    
    binding
    These entries allow Managed objects to be added to the dependent context. They have the form:
    { name; binding ; object_id; }
    E.g., { UserBaseCollection ; binding; TRSRoot/users; }
    

    Building Root MOs

    You must implement the interface COM.ibm.jaws.services.sroot.SRootMO. There is a class COM.ibm.jaws.services.sroot.MOBaseSRootMO that implements this interface. You can just subclass this and override any methods you need to change. Or you can copy the source for this file into your class and modify to meet your needs. Or, if you are working with the MOFW you can build your Manageable object and then use the SRootMO emitter to generate an SRootMO version of our object. If you take this path then you have nothing to else to do.

    If you want to register an object that is not an MOFW Manageable object then subclass MOBaseSRootMO. For a simple root object that has no external state you could just subclass MOBaseSRootMO and do nothing more. If you have external state then override the method internalizeFromStream as shown above.

    If you want to be able to persistently save changes to your object's state in its registration file then override the method externalizeToStream. This could be done with code like the following (building on the example of the previous section).

    public void externalizeToStream(OutputEDStream out) {
      super.externalizeToStream(out);
      out.writeInt(field1);
      out.writeFloat(field2);
      out.writeString(field3);
    }