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

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

• check the changed ORB.init() call details
• check the IDL compiler changes
• update application/applet if any of the above changes make that necessary or desirable
• recompile IDL with new IDL compiler
• recompile all sources, including those generated from the IDL
• if problems occur, check the troubleshooting tips

ORB.init()

• Singleton ORB

An ORB.init() call with no parameters returns an instance of a singleton ORB. There is only one instance of the singleton ORB in a VM. The singleton ORB has restricted functionality, mainly for security reasons in applets. Only the following operations may be called on the singleton ORB:-
 
      create_list()
      create_named_value()
      create_exception_list()
      create_context_list()
      get_default_context()
      create_environment()
      create_xxx_tc(), where xxx is one the defined typecode types
      get_primitive_tc()
      create_any()
      create_output_stream()

An attempt to call any other ORB operation on the singleton ORB will result in a system exception.
 

• Fully functional ORB

Any of the forms of ORB.init() with parameters returns a new, fully functional ORB.
Important: In OrbixWeb 3.0, each call in the same VM returned the same ORB (i.e. _CORBA.Orbix), but in OrbixWeb 3.1 each call returns a different and new ORB. This adds considerable flexibility to some applications, as each new ORB is completely independent from any other (e.g. in its configuration, connections, listener ports, server object tables etc.), and also facilitates applet separation. Some important points to note in this respect are:
 

• _CORBA.Orbix now refers to the "default ORB", which is the first full ORB created. If that ORB is destroyed, this becomes null until another ORB is created.Direct use of _CORBA.Orbix is deprecated.
• Only server objects connected to the default ORB can be "persistent" and can be contacted via orbxid (e.g. by clients calling bind). Server objects connected to other ORBs in the VM listen on other ports unknown to orbixd and should be regarded as transient objects.
• Features such as smart proxies, loaders etc. are associated with particular ORB instances. By default, this is the default ORB. The API has been extended to allow any of these to be associated with a selected ORB instance.
• There is now an additional optional ORB parameter for each generated bind call. The supplied ORB is used to build the proxy and establish a connection to the target server when required.
• As configuration is now per-orb, static calls on the Config class should be replaced by calls on the object returned by the config() operation on the selected orb, e.g. Config.get_BIND_USING_IIOP() should be replaced orb.config().get_BIND_USING_IIOP()

IDL compiler changes

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

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 ifr executables are from Orbix 2.3c02-17 as well.

New features

Enhanced Diagnostics

  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

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

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

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

•     IT_DEFAULT_IIOP_VERSION

This controls the IIOP version embedded in  IORs (interoperable object references) produced in OrbixWeb servers which indicates what versions of IIOP the target supports, and also the version of messages sent by a client (as long as it is less than or equal to that of the target). It is set to "10" i.e. IIOP version 1.0 by default. You must set this to "11" in servers to allow clients to use fragmentation.
•     IT_BIND_IIOP_VERSION

Since bind calls don`t return IORs created by servers, but create ones themselves, a separate version control is applied to the creation of these IORs. This is "10" i.e. version 1.0 by default. It should only be set to "11" if you are sure that the target server supports IIOP 1.1. If so, set it to "11" if you want requests on the object returned by bind to be able to use  fragmentation.
•     IT_SEND_FRAGMENTS

By default, messages sent by OrbixWeb 3.1 are not fragmented. If this item is set to "true" and the target supports IIOP version 1.1 or higher, then larger messages will be sent as fragments bounded by IT_BUFFER_SIZE

Faults Fixed

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

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

• NO_PERMISSION exception when using ORB.init()

This is probably because an unpermitted operation is being called on the singleton ORB : see above for details. Ensure IDL has all been recompiled.
• NullPointerException or CORBA INITIALIZE exception on first calling into ORB (e.g. during first bind call)

This is probably because a full ORB.init() with parameters has not been called
• "org.omg.CORBA.BAD_OPERATION: The delegate is null." exception

Possibly the IDL has been compiled with -jNoC or -jOMG but the object in question is an implementation object and has not been explicitly connected using ORB.connect().
• ServerManager on Unix doesn't display properly

Ensure your window manager is set for appropriate X terminal mode
• COMM_FAILURE contacting orbixd

Previously the orbixd used two separate ports for IIOP and Orbix Protocol and your client may still be configured to use separate ports. The orbixd executable in OrbixWeb 3.1 listens on a single port and your configuration must reflect this.