VisiBroker for Java 7.0 Migration Guide



VisiBroker for Java 7.0 Migration Guide

Introduction

Purpose

Summary

Organization

Abbreviations and Conventions

Development

IDL Compiler

Caffeine (pass by value)

Code Migration

osfind tool

Runtime

Object Request Broker (ORB)

Basic Object Adapter (BOA)

DII/DSI

Dynamic Anys (dynany)

VisiBroker Features

TIE approach

Object Wrappers

Service Activators

ORB Manager API

URLNaming

Event Handlers

Interceptors

Smart Stubs

Properties

Bind Options

Connection and Request Timeouts

Properties Change

Osagent

GateKeeper

Event Service

Location Service

Naming Service

Interface Repository (irep)

Object Activation Daemon (OAD)

Native Messaging

VisiBroker for Java 7.0 Migration Guide

Introduction

Purpose

The purpose of this guide is to provide recommendations for migrating an application from VisiBroker for Java 3.x, VisiBroker for Java 4.x, VisiBroker for Java 5.x, and VisiBroker for Java 6.x to Borland VisiBroker 7.0 (VisiBroker for Java 7.0). For each VisiBroker for Java 3.x/4.x/5.x/6.x feature this document lists the key changes made in VisiBroker for Java 7.0, identifies known migration issues, and makes specific recommendations. For each feature a list of resources is provided for the recommendation.

This guide does not cover new features for which there is no VisiBroker for Java 3.x/4.x/5.x/6.x equivalent.

Summary

Very few, if any, non-trivial applications will migrate directly from VisiBroker for Java 3.x to VisiBroker for Java 7.0 without code and property changes. A relatively clean application based on OMG standard services and the BOA should require only minimal modifications. Other applications may require substantial rework. The amount of change depends on how many vendor specific VisiBroker features are used by the application, and whether the application was tuned to rely on observed, but not documented, ORB runtime behavior.

This guide identifies the areas where an application may be most affected so that developers can plan accordingly.

Product areas that require significant modifications or reconfiguration when migrating from VisiBroker for Java 3.x to VisiBroker for Java 7.0 are noted with headings in the color red.

In general the migration from VisiBroker for Java 4.x/5.x/6.x to VisiBroker for Java 7.0 is straightforward and requires minimal effort.

For these reasons this document is primarily aimed at VisiBroker for Java 3.x users. Minor differences between VisiBroker for Java 4.x/5.x/6.x and VisiBroker for Java 7.0 are not covered.

Organization

This document is organized into the following general topic areas:

Development Tools

VisiBroker Runtime

VisiBroker Features

VisiBroker Services

Abbreviations and Conventions

The list of abbreviations used for this document:

FAQ: FAQ supplied by Borland.

DOC: Product documentation.

EXM: Product examples.

PUB: Commercial Publication.

WHT: Publicly available white paper or technical note.

REL: Release notes for the product

<install> is the root installation directory for Borland Enterprise Server, VisiBroker Edition

/ is the directory or file system separator for Unix. Windows users should make the obvious assumption when file paths are shown in Unix syntax.

Development

IDL Compiler

Key Changes.

The idl compiler has been rewritten to support the OMG CORBA 2.6 IDL to Java language mapping. Options are provided to generate older style BOA based classes for server side implementations.

VisiBroker for Java 3.x IDL extensible structs are no longer supported. IDL value types have replaced them in VisiBroker for Java 4.x/5.x/6.x and 7.0. Command line options have changed. See list under “Known Issues” below.

Known Issues.

Due to changes in the IDL/Java language mapping some existing IDL may not compile.

Some complex make systems that relied extensively on idl2java options to place code in specific packages or locations may not works with the new idl2java tool.

VisiBroker for Java 3.x idl2java options that have been eliminated:

  • -back_compat
  • -smart_stub
  • -all_serializable
  • -serializable
  • -no_stub
  • -no_toString
  • -deprecated_skel
  • -pseudo
  • -interface

VisiBroker for Java 3.x idl2java options that have been superceded:

  • -portable has been superceded by the VisiBroker for Java 7.0 -dynamic_marshal option.
  • -incl_files_code has been superceded by the VisiBroker for Java 7.0 -gen_included_files option.
  • -no_skel has been superceded by the VisiBroker for Java 7.0 -no_servant option.
  • -no_toString has been superceded by the VisiBroker for Java 7.0 –no_Object_methods option.

VisiBroker for Java 4.x/5.x/6.x idl2java options that have been eliminated/superceded: none

Recommendation.

It is not likely that most applications will encounter the known issues described above. If build problems are encountered it is important to review and understand the options available in the current idl2java tool. Since idl2java is always undergoing improvements, it is best to consult the latest release notes and the help output from the tool for the available options.

IDL that includes the VisiBroker for Java 3.x proprietary extensible struct IDL type will need to be rewritten to use standard IDL.

Further Resources.

EXM: <install>/examples/vbe/obv for an example of IDL valuetypes.

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 13, Using IDL

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 30, Using Valuetypes

REL: <install>/readme.html

Caffeine (pass by value)

Key Changes.

The Java to IDL mapping is now based on the OMG specifications version 1.3. IDL valuetypes are now

supported and completely replace the proprietary VisiBroker for Java 3.x extensible struct feature.

Known Issues.

The proprietary pass-by-value or caffeine feature of VisiBroker for Java 3.x is no longer available or supported.

Java to IDL to Java closure is not supported. This may affect a build process that relied on such closure.

VisiBroker for Java 3.x applications using pass-by-value are not interoperable with VisiBroker for Java 4.x, 5.x, 6.x or 7.0 applications using valuetypes.

Recommendation.

Applications that relied on pass-by-value/caffeine or made use of extensible structs directly in IDL will need to be updated to use the RMI-IIOP and valuetype features.

Developers can no longer assume that mapping java to IDL and then back to Java will result in compilable code.

Further Resources.

EXM: <install>/examples/ vbe /rmi-iiop for an example of using java2iiop.

EXM: <install>/examples/ vbe/rmi-iiop-server for an example of server side java2iiop.

EXM: <install>/examples/ vbe/obv for an example of IDL valuetypes.

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 28, Using RMI over IIOP

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 30, Using Valuetypes

Code Migration

Key Changes.

Since many product features have changed and many Java class names are not the same, a basic migration tool has been provided to make the minimal edits required to allow existing code to compile.

Known Issues.

Code migration performed by the “migrator” tool is incomplete. Some code must be modified by hand.

The “migrator” makes no attempt to migrate from BOA based servants to POA based servants.

Recommendation.

If planning to continue using the BOA, the migrator tool is a convenient method to make the initial set of necessary code edits. It is a first step in the migration of existing code, but other changes are usually required.

Specific code changes not handled by the migrator tool are identified elsewhere in this technical note where appropriate.

Further Resources.

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 33, Using the BOA with VisiBroker

REL: <install>/readme.html

osfind tool

Key Changes.

The osfind tool was completely rewritten in Java in VisiBroker for Java 4.x. This is true for VisiBroker for Java and VisiBroker for C++. Therefore the tool now requires that a compatible Java VM be in the execution path of the user.

Prior to VisiBroker for Java 4.x the osfind tool was a platform native executable based on the VisiBroker for C++ ORB runtime. Thus it exhibited behavior consistent with VisiBroker for C++. Starting in VisiBroker for Java 4.0 the osfind tool is written completely in Java and is based on the VisiBroker for Java ORB runtime. Thus it exhibits behavior consistent with VisiBroker for Java. In situations where there are differences in behavior between VisiBroker for C++ and VisiBroker for Java, the osfind tool will exhibit behavior consistent with VisiBroker for Java.

Known Issues.

There are some minor behavioral differences that can be attributed to the use of the VisiBroker for Java runtime rather than the VisiBroker for C++ runtime. Specifically, the way in which VisiBroker for Java applications locate an osagent is slightly different than the way in which VisiBroker for C++ applications locate an osagent. This can lead to different results when comparing the old (VisiBroker for Java 3.x) and new (VisiBroker for Java 4.x/5.x and VisiBroker for Java 6.x) osfind utilities if the osagent network is not complete and symmetric.

Some VisiBroker for C++ users may not routinely have a Java VM in the execution path.

Recommendations.

Make sure that a Java VM is available and in the execution path if using the osfind tool. Note that osfind is intended to be a development tool and may be deprecated in the future. If possible, eliminate any reliance on osfind in deployed applications and use the location service API directly.

Further Resources.

EXM: <install>/examples/ vbe/locate/Find.java for an example of using the location service API.

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 15, Using the Location Service

DOC: VisiBroker for Java API reference, <install>/doc/vbe-api-doc/index.html

Runtime

Object Request Broker (ORB)

Key Changes.

The VisiBroker for Java 6.0 ORB is compliant with the OMG CORBA 2.6 specification as well as the corresponding IDL/Java and Java/IDL language mappings (version 1.2 and 1.3 respectively). Changes to the ORB runtime between VisiBroker for Java 7.0 and 3.x are too numerous to list here. This change primarily affects VisiBroker for Java 3.x applications.

Known Issues.

Please refer to the release notes for further information.

Recommendation.

Please refer to the release notes for further information.

Further Resources.

REL: <install>/readme.html

Basic Object Adapter (BOA)

Key Changes.

The Basic Object Adapter was deprecated in version 2.2 of the CORBA spec. VisiBroker for Java 7.0 provides a compatibility layer that allows most BOA based applications to operate without significant changes. The BOA compatibility layer is built on the newer POA architecture.

The idl2java compiler no longer generated BOA mapping classes by default. The -boa option must be used with idl2java in order to generate BOA mapping classes.

Known Issues.

See the VisiBroker for Java Developer’s Guide (PDF version), Chapter 33, Using the BOA with VisiBroker, for a list of known BOA migration issues.

Although the BOA compatibility layer does a good job of hiding the underlying POA implementation, there are several cases where problems may be encountered when migrating BOA based code.

  • The BOA allows objects and servants to be used interchangeably. Thus it was possible to access non-IDL implementation methods on an object reference in the same address space as the servant or use Java type casting to convert an object reference parameter to an implementation class in many cases.
  • The VisiBroker 3.x runtime has an optimization that will implicitly activate (call obj_is_ready) on objects that are passed out of the address space.
  • In addition, VisiBroker 3.x provided several convenience methods such as _orb() that allowed a servant to retrieve its ORB instance. Many BOA based applications have come to rely on these capabilities.

However the POA enforces strict separation of objects and servants, and has formal support for implicit activation. A BOA based application may in some cases need modifications to account for these differences in behavior.

In rare cases, it may be necessary to obtain access to the underlying POA (used by the BOA compatibility layer) in order to obtain equivalent capability or work around an incompatibility between VisiBroker for Java 3.x code and the VisiBroker for Java 7.0 BOA compatibility layer.

Recommendation.

Use the BOA compatibility layer in only the simplest cases.

We recommend that developers modify application to use the POA directly. Although it is appealing to migrate using existing BOA based code, it is now non-standard and subtle issues that arise due to the differences between BOA and POA may be difficult to resolve.

Further Resource.

EXM: <install>/examples/ vbe/boa/bank

EXM: <install>/examples/ vbe/boa/boa2poa

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 33, Using the BOA with VisiBroker

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 9, Using POAs

FAQ: <install>/doc/faqs/VisiPOAFAQ.html

REL: <install>/readme.html

DII/DSI

Key Changes.

There should be no major changes in DII or DSI functionality other than adherence to a later version of the OMG CORBA specifications, which may have corrected errors/issues in the earliest specification.

Known Issues.

None.

Recommendation.

None.

Further Resources.

EXM: <install>/examples/ vbe /basic/bank_dynamic

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 22, Using the Dynamic Invocation Interface

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 23, Using the Dynamic Skeleton Interface

REL: <install>/readme.html

Dynamic Anys (dynany)

Key Changes.

The Dynamic Any capability is per OMG CORBA 2.6 spec level in VisiBroker for Java 7.0. The OMG has refactored the dynamic any creation methods from the ORB to the DynAnyFactory class, which can be obtained using resolve_initial_references().

No significant changes were made for VisiBroker for Java 7.0.

Known Issues.

Source code requires modifications to comply with the latest spec. No compatibility layer or migration tool support is provided.

Recommendation.

Consult the latest documentation to rework areas of the code that are not in strict compliance with CORBA 2.3 or later. Compare the dynany example in VisiBroker for Java 3.x to the example in VisiBroker for Java 7.0 to see the major changes (use of the DynAnyFactory class rather than the ORB to create and manipulate dynamic anys).

Further Resources.

EXM: <install>/examples/vbe/dynany

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 29, Using the dynamically managed types

DOC: VisiBroker for Java API reference, <install>/doc/vbe-api-doc/index.html

REL: <install>/readme.html

VisiBroker Features

TIE approach

Key Changes.

The TIE approach is implemented as a POA based servant template in VisiBroker for Java 4.x, 5.x, 6.x and 7.0. In order to support this new approach the following differences are noted between VisiBroker for Java 3.x and VisiBroker for Java 4.x/5.x/6.x and 7.0:

The naming convention has changed. The TIE servant class is now <type>POATie rather than _tie_<type>

The <type>POATie extends <type>POA rather than <type>ImplBase.

  • The <type>POATie has an additional constructor that accepts a POA as the second parameter. This is
  • to allow the servant to explicitly override the _default_POA() method. Otherwise, the default

implementation of the _default_POA() method will be used by the TIE servant. There is no equivalent concept for the BOA based _tie_<type> servant.

Since <type>POATie is a POA based servant implementation, it must be activated on a POA and is subject to all the POA architectural requirements.

  • The older style _tie_<type> can be generated by adding the "-boa" option to idl2java or idl2cpp. This
  • generates a _tie_<type> that extends from <type>ImplBase. A BOA compatibility layer allows the <type>ImplBase to compile and be used with the BOA as before.

Known Issues.

VisiBroker for Java 3.x code that uses the older style _tie_<type> may encounter a problem with the BOA compatibility layer. In VisiBroker for Java 7.0 neither the _tie_<type> nor the <type>ImplBase are real servants. It is not uncommon for VisiBroker for Java 3.x BOA code to take advantage of the fact that the VisiBroker for Java 3.x implementation treated servants and objects interchangeably in most cases. Methods that take a CORBA object as a parameter will not have direct access to the actual implementation (servant) so some non-standard code that worked in VisiBroker for Java 3.x, such as type casting the CORBA object to the corresponding implementation object, are no longer possible.

Recommendation.

Use the POA capability directly if possible.

Assess whether existing TIE based code is compatible with the BOA compatibility layer. If not, use the POA and (optionally) a servant based <type>POATie. It is usually more difficult and non-standard to try to work around BOA compatibility layer issues than it is to simply use the POA directly.

  • Assess whether the TIE approach is still appropriate given the added capabilities offered by the POA. The TIE approach offers advantages in cases where complex implementation inheritance is needed, or where very simple legacy classes exist that present IDL compatible interfaces. In all other cases it is better to simply write the necessary servant code. If the application falls into one of the special cases where the TIE approach offers an advantage, use the servant based <type>POATie and the POA rather than the older style _tie_<type> and the BOA.

Further Resources.

EXM: <install>/examples/vbe/basic/bank_tie

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 33, Using the BOA with VisiBroker

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 11, Using the tie mechanism

DOC: VisiBroker for Java Developer’s Guide (PDF version), Chapter 9, Using POAs