OrbixWeb 3.1 Release Notes


The following notes should be read before using this product..

Note that OrbixWeb 3.1 implements revision 1.1 of the OMG IDL/Java mapping, which has resulted in changes in the  ORB initialisation interface. Some applications may need some changes here.  See the  ORB.init() notes for details.

Table Of Contents

  1. General
  2. Migrating from OrbixWeb 3.0
  3. New features
  4. Faults fixed
  5. Known Issues

The use of this software is subject to the terms and conditions of the "IONA Technologies License Agreement" which has been read by your company and contains exclusion of warranty provisions, limitation of liability and exclusion of third party intellectual property right infringement indemnity. In the event that your company has not read such an agreement, you should do so immediately as any use of the software by you shall indicate your acceptance of the terms and conditions contained therein.

Copying, modification, reverse engineering and disassembly of the software and/or documentation is strictly prohibited. Any use of this software is prohibited if such an agreement has not been accepted. The software and any related documentation is (c) Copyright IONA Technologies PLC. 1995-1998.


GENERAL

This is product is a fully functional CORBA 2 Java client/server development and runtime environment based on (and functionally equivalent to) the Orbix product. OrbixWeb 3.1 implements revision 1.1 of the OMG IDL/Java mapping specification.

OrbixWeb clients and servers are completely Java based applications or applets, targetted for JDK 1.1 / JDK 1.0.2.

Two communication protocols are fully supported - OMG IIOP for interoperability with any CORBA 2 compliant ORB (including Orbix and OrbixWeb), and Orbix protocol for homogeneous Orbix/OrbixWeb environments. The default protocol is IIOP.

Note that these release notes are meant only as a supplement to the documentation, which should be consulted for a detailed programming and reference guide.
 

Migrating from OrbixWeb 3.0

Applications and applets should need minimal changes to work with OrbixWeb 3.1. The following straightforward steps are recommended:-

ORB.init()

The Java mapping distinguishes between a fully functional ORB and what is called the "singleton ORB". In OrbixWeb 3.0  no distinction was made, but in OrbixWeb 3.1 there are important differences between these ORB types, compliant with the revised mapping. Which type of ORB is returned is determined by the form of the ORB.init() call as described below.

IDL compiler changes

As a result of the new singleton ORB restrictions, the code generated by the OrbixWeb V3.0 IDL compiler for implementation object constructors will fail as it calls "connect" on the singleton orb. The new IDL compiler now generates "connect" calls on _CORBA.Orbix, which supports compatibility for OrbixWeb 3.0 applications so all IDL should be recompiled.

A new switch -jNoC is provided which prevents these "connect" calls being generated (the -jOMG switch also prevents this code generation). If these switches are used, the application must explicitly connect the implementation object after creation and before it is used. For compatibility with OrbixWeb 3.0 applications it is more convenient not to apply these switches initially, but using explicit connect calls is recommended anyway.

Note that the revised mapping stipulates that insertion of non-primitive types into Anys is by reference - previously the value was copied. This change results in greater efficiency when handling Anys. Some applications may depend on copy semantics in Anys : this can be achieved for user-defined types by calling the generated helper class "write" method, supplying the stream returned by the Any operation create_output_stream().

The "HolderHolder" classes are no longer used by the generated code.

Orbixdj

Several of the features of orbixd which were not in orbixdj in OrbixWeb 3.0 have now been added. These include invoke/launch rights functionality and locator functionality. Also orbixdj can be incorporated as an implementation object in any server.

In this release, in-process servers must use the default process orb i.e. _CORBA.Orbix.. To use in-process servers in this release, your server should initialize the ORB using:-
        IE.Iona.OrbixWeb.CORBA.ORB.init(...) call
This always returns the default ORB in in-process mode.The OMG full orb iniitialisation call org.omg.CORBA.ORB.init(...) cannot be called in in-process mode.

orbixd and ifr

The orbixd  executables are from Orbix 2.3c02-17. It is important to note that (unlike the orbixd in OrbixWeb V3.0) this orbixd listens on the same port for IIOP and Orbix protocol. The configuration tool thus configures only one port for both IIOP and Orbix protocol by default, which works for both orbixd and orbixdj in this release. This can be changed if using a previous version of orbixd.

The ifr executables are from Orbix 2.3c02-17 as well.

New features

Enhanced Diagnostics

There is much fuller diagnostics output available in this release than previously. The output is controlled as before by calling setDiagnostics. However, the meanings of each diagnostics level is different. The diagnostics are now broken down by component, each associated with a particular level. Thus the following are defined (in IE.Iona.OrbixWeb.Features.DiagnosticsLog):

  public static final int _LO=1;
  public static final int _HI=2;
  public static final int _ORB=4;
  public static final int _BOA=8;
  public static final int _PROXY=16;
  public static final int _REQUEST=32;
  public static final int _CONNECTION=64;
  public static final int _DETAILED=128;

To get diagnostics output from particular components, add the values associated with each component together. The values _LO and _HI just refer to previous diagnostics levels 1 and 2. The value _DETAILED is of special significance, as this controls the amount of diagnostics produced by the components. Setting this means that all diagnostics from the selected components will be produced.

An example is getting full-detail diagnostics associated with the BOA and requests: this is done by adding 8 + 32 + 128 =168 and setting this value in setDiagnostics.

Full diagnostics is got by setting the value to 255 i.e. the result of adding all the above together. This produces very voluminous output including full buffer dumps of messages.

The most flexible way of using diagnostics is to pass the desired value using a system parameter on startup (e.g. -DOrbixWeb.setDiagnostics=255 for an application).
 
The diagnostics log can be overridden by an application so that diagnostics can be e.g. redirected to a file. This is done by overriding the "entry(ORB orb,int current_diag, int component_diag,Stringable component,String message, boolean isADetail)" operation in DiagnosticsLog and setting the new log on the ORB using ORB.setDiagnosticsLog(Features.DiagnosticsLog l). The default entry function checks the diagnostics level, then outputs the message to System.out, prepended by a short string describing the component producing the diagnostic.
 

Basic Instrumentation Support

OrbixWeb 3.1 adds support for instrumentation and management using a new class, IE.Iona.OrbixWeb.Features.InstrumentBase . This class provides an interface of which application code can provide an implementation; this implementation is then registered with the ORB. From that point until the implementation is unregistered, instrumentation data from OrbixWeb will be logged with the InstrumentBase object by calling the interface methods with arguments of the appropriate type; for example, when a new object is connected to the object adapter, the InstrumentBase.newObj() method is called with the newly-connected object as a parameter.

In addition the InstrumentBase interface provides some extra functionality; for example, log messages can be intercepted with the InstrGetDiagnostics() method. This method is passed a MgmtLogMessage object as an argument, which contains the logged message itself, as a String in variable content, and the diagnostic level it was logged at, as an int in variable level (see the Diagnostics Log section). In order to receive diagnostic messages, the boolean variable m_instrumentDiagnostics must be set to true.

Servers can be suspended by setting the boolean variable m_suspend to true, and unsuspended by setting it to false. Suspension in this case means that requests from client ORBs are not processed, and instead an IT_SUSPEND system exception (minor code 10641) is sent to the client.

The full interface for InstrumentBase follows.

public class IE.Iona.OrbixWeb.Features.InstrumentBase {
  public void InstrGetDiagnostics (MgmtLogMessage message);
  public void startServer (String servername, long timeout);
  public void endServer (String servername);
  public void newObj (org.omg.CORBA.Object obj);
  public void deleteObj (org.omg.CORBA.Object obj);
  public void newConnection (ClientConnection conn, boolean isMgmtChannel);
  public void endConnection (ClientConnection conn);
  public void inRequest (org.omg.CORBA.Request obj);
  public void outReply (org.omg.CORBA.Request obj);
  public void outRequest (org.omg.CORBA.Request obj);
  public void inReply (org.omg.CORBA.Request obj);

  public boolean m_suspend = false;
  public boolean m_instrumentDiagnostics = false;
}
 

Service Context Handlers

IIOP request and reply messages include a field in the header called the Service Context List. This contains optional Service Contexts (SCs), which have an id and some data marshalled as a sequence of octest. These can be used by ORB vendors and others to pass information related to the requests/replies. See the IIOP specification for full details.

OrbixWeb3.1 includes support for Service Context handling This API allows Service Context Handlers to be registered which intercept requests and replies and can store and retrieve service contexts.

A ServiceContext Handler is implemented by first deriving a class from the ServiceContextHandler base class i.e. IE.Iona.OrbixWeb.Features.ServiceContextHandler. The following methods must then be implemented :

/* constructor must register context id */
public mySrvCtx (int contextID) {
super (contextID);
}

public boolean incomingRequestHandler (Request req);
public boolean outboundRequestHandler (Request req);
public boolean incomingReplyHandler (Request req);
public boolean outboundReplyHandler (Request req)

Note that Request refers to IE.Iona.OrbixWeb.CORBA.Request.

An instance of this classes is created in the client with a unique identification number and registered with the ORB by calling either of the
two registration methods on the ORB object:

void registerPerRequestServiceContextHandler (ServiceContextHandler CtxHander );
void registerPerObjectServiceContextHandler (ServiceContextHandler CtxHander, org.omg.CORBA.Object HandledObject );

Registering the handler as per request  causes the handlers request/reply handler methods to be added to a list to get called at the appropriate interception point for any request. Registering the handler with the per object  causes the handlers request/reply handler to be added to a list to get called for request/replies associated with the specified target object.

incomingRequestHandler is called when an incoming request arrives in a server at the point where the SCL has just been unmarshalled. This operation can access the unmarshalled SCL, passing the SC id to access the specific SC its interested in.

outboundRequestHandler is called when an outgoing request is being marshalled. It can add an SC to the SCL for marshalling.

incomingReplyHandler is called when an incoming reply arrives in a client at the point just after the SCL has been unmarshalled. This operation can access the unmarshalled SCL,  passing the SC id to access the specific SC its interested in.

outboundReplyHandler is called when an outgoing reply is being marshalled in the server. It can add an SC to the SCL for marshalling.

Adding an SCL for marshalling is done by creating an instance of an IE.Iona.OrbixWeb.Features. ServiceContext, populating its context_data attribute (a byte array) and calling addServiceContext (ServiceContext) on the request.

Accessing an unmarshalled SCL is done by calling the request getServiceContext (int contextID) method and passing the context id of interest.

Context handlers can be unregistered by calling the appropriate unregistration methods on the ORB :
void unregisterPerRequestServiceContextHandler (ServiceContextHandler CtxHander);
void unregisterPerObjectServiceContextHandler (ServiceContextHandler CtxHander);

By default ServiceContext support is switched off and is only enabled by a call to enableServiceContextList ( boolean state ) on the current ORB
object. The state can be determined by the ORB method boolean sclEnabled();
 

IIOP 1.1 Fragmentation

IIOP 1.1. allows messages to be sent in fragments. The main benefit of this is that the sending ORB can send fragments before all the data is marshalled, while the receiving ORB can start unmarshalling the message before it has all arrived. This increases parallelism and thus improves overall dispatch speed for very large messages. Another benefit is lower memory consumption.

A restriction of the specification of fragmentation in IIOP 1.1 implies that only one fragmented message can be sent over a connection at a time from start to finish of the message i.e. no interleaving of fragments is allowed. This may cause sending threads to block for some time if a client has multiple threads concurrently sending large messages to the same server.

OrbixWeb 3.1 supports sending and receiving fragments. The following configuration items control this and other IIOP version-related functionality

Faults Fixed

All of the public fault fixes of OrbixWeb V3.0 up to and including Upgrade 4 are included, as well as the following:-
These are the faults fixed in the OrbixWeb classes and IDL compiler components - the IFR and orbixd are based on Orbix 2.3c02-17 and incorporate the corresponding bug fixes.

FT 20140 smart proxies not created when obj ref enters client address space
FT 12221 union with boolean discriminator does not marshal correctly
FT 11181 smart_proxy demo in a module - wrong interface id
FT 14060 constructor in UserException causes problems with iiop10.jar
FT 15841 Missing classes in org.omg.CosNaming
FT 11920 "out of memory" compiling the generated code from recursive sequences
FT 12280 extracting sequences of sequences from Any fails
FT 12084 opaques as return types are broken
FT 19880 wrong interface marker or type id when inheritance in use
FT 12140  IDL compiler produces incorrect code when a type code appears in  struct.
FT 12561 generated code to use ORB.get_primitive_tc(TCKind.tk_string), not ORB.create_string_tc(0)
FT 12565 What is returned using a post-object filter overwrites the result of the method
FT 16200  Error is not scoped as java.lang.Error in generated code, clashes with idl   'exception Error'
FT 16940  can't set union discriminator to value that doesn't match a case
FT 21340  IDL compiler treating typedefed string as a zero bounded string.
FT 23420  Compiler treated typecode idl types as strings.
FT 25360  Sequence of sequence of octets as return types fail
FT 28460, 27621 pass JVM parameters to servers at launch time with orbixdj
FT 18461 can launch orbixdj as standard OrbixWeb server
FT 18821,10641 client doesn't reconnect when daemon brought down and back up again putit counterFactory -j

Known Issues

FT 11880,25300 (Orbix protocol) error marshalling nested sequence with a zero length
FT 11261 putit with multiple markers doesn't work with orbixdj (it does with orbixd)
FT 15801 incorrect line numbers given for errors in included file
FT  11840 re-opening of modules across files
FT 28860 alias typecode generation
FT 31000 recursive sequence Typecode and Any handling fails

Important Note for HP-UX users:

A bug in the HP-UX JDK JIT compiler can cause a segmentation violation when used in conjunction with some OrbixWeb applications. If this occurs, ensure the JIT is turned of by specifying "-nojit" on the command line when running OrbixWeb applications. For example, you can register a specific server so that it is launched with no JIT as in the following example (note the required space between the opening quote and the -nojit option):
            putit -j CounterFactory " -nojit Thread1.javaserver1"

Troubleshooting Tips

OrbixWeb 3.1 notes - Last Modified: Aug 13 1998
Part of the OrbixWeb 3.1 release notes