# CORBA Compatibility Information - J2SE 5.0

- CORBA API Changes Between J2SE 1.4.x and J2SE 5.0.x
- Official Specifications for CORBA support in J2SE 5.0.x
- Other Compatibility Information

# CORBA API Changes Between J2SE 1.3 and J2SE 5.0

This document contains information regarding all of the API changes related to CORBA functionality between JDK 1.3 and 5.0. The changes have been made to make the APIs for the CORBA technology shipped in the JDK 5.0 compliant to the CORBA 2.3 mapping as specified by the following OMG documents:

- CORBA 2.3.1 (formal/99-10-07)
- IDL to Java language mapping (ptc/00-01-08)
- Java to IDL language mapping (ptc/00-01-06)
- Interoperable Naming Service (/ptc/00-08-07)
- Portable Interceptors (ptc/2001-03-04)

## API changes to `org.omg.COSNaming` classes

To comply with the IDL to Java mapping specified by the CORBA Version 2.3 specification, the following `org.omg.COSNaming` classes have been regenerated from the `idlj` compiler shipped with the JDK. This change (CCC 4284015) consists of the following API changes. Compatibility impact: None.

To conform with CORBA V (2.3) All Helpers Section 1.5.2 Spec ptc/00-01-08.pdf, all Helpers are now abstract public classes. Below is the list of all Helper classes under `org.omg.CosNaming` that have been changed to abstract public classes.

`
- BindingHelper.java
- BindingIteratorHelper.java
- BindingListHelper.java
- BindingTypeHelper.java
- IStringHelper.java
- NameComponentHelper.java
- NameHelper.java
- NamingContextHelper.java
- AlreadyBoundHelper.java
- CannotProceedHelper.java
- InvalidNameHelper.java
- NotEmptyHelper.java
- NotFoundHelper.java
- NotFoundReasonHelper.java
`

To conform with Section 1.7 OMG Spec ptc/00-01-08.pdf, Mapping for Enum, the mapping for the following Enum constructors is changed to protected.

CLASS | BEFORE | NOW
--- | --- | ---
`BindingType.java` | private BindingType( int ) | protected BindingType( int )
`NotFoundReason.java` | private NotFoundReason( int ) | protected NotFoundReason( int )

1. To conform with CORBA 2.3 spec (ptc/00-01-08.pdf), Deletion of constructors in Stub classes, the following constructors have been deleted.

CLASS | BEFORE | NOW
--- | --- | ---
`_BindingIteratorStub.java` | public _BindingIteratorStub(org.omg.CORBA.portable.Delegate d) | The constructor is deleted.
`_NamingContextStub.java` | public _NamingContextStub(org.omg.CORBA.portable.Delegate d) | The constructor is deleted.

2. To conform with CORBA 2.3 spec (ptc/00-01-08.pdf), the following exceptions have been changed.

CLASS | BEFORE | NOW
--- | --- | ---
`AlreadyBound.java` | public final class AlreadyBound extends org.omg.CORBA.UserException implements org.omg.CORBA.portable.IDLEntity | public final class AlreadyBound extends org.omg.CORBA.UserException
`AlreadyBound.java` | Only default constructor | Add new constructor public AlreadyBound (String reason)
`CannotProceed.java` | public final class CannotProceed extends org.omg.CORBA.UserException implements org.omg.CORBA.portable.IDLEntity | public final class CannotProceed extends org.omg.CORBA.UserException
`CannotProceed.java` | Only default constructor | Add new constructor public CannotProceed (String reason)
`InvalidName.java` | public final class InvalidName extends org.omg.CORBA.UserException implements org.omg.CORBA.portable.IDLEntity | public final class InvalidName extends org.omg.CORBA.UserException
`InvalidName.java` | Only default constructor | Add new constructor public InvalidName (String reason)
`NotEmpty.java` | public final class NotEmpty extends org.omg.CORBA.UserException implements org.omg.CORBA.portable.IDLEntity | public final class NotEmpty extends org.omg.CORBA.UserException
`NotEmpty.java` | Only default constructor | Add new constructor public NotEmpty (String reason)
`NotFound.java` | public final class NotFound extends org.omg.CORBA.UserException implements org.omg.CORBA.portable.IDLEntity | public final class NotFound extends org.omg.CORBA.UserException
`NotFound.java` | Only default constructor | Add new constructor public NotFound (String, org.omg.CosNaming.NamingContextPackage.NotFoundReason, org.omg.CosNaming.NameComponent[])

3. To conform with the CORBA 2.3 specification, the following classes have been added.

- `NamingContextPOA.java`
- `BindingIteratorPOA.java`

To conform with the CORBA 2.3 specification, the following classes are deprecated.

- `_NamingContextImplBase.java`
- `_BindingIteratorImplBase.java`

## API changes to `org.omg.CORBA`

- To conform to OMG spec 99-07-57, IDL to Java mapping, the following methods have been changed.

  - The signature of method `org.omg.CORBA.Any.insert_fixed(java.math.BigDecimal, org.omg.CORBA.TypeCode)` is changed to throw an `org.omg.CORBA.Bad_INV_ORDER` exception. System exception does not need to be declared in user's code. (CCC 4340915)
  - The method `TypeCode.equivalent` is defined as abstract. BEFORE: threw a `NO_IMPLEMENT` exception. Compatibility impact: Minimal impact for licensees, not for end user. Licensees need to provide a dummy implementation of this method. (CCC 4340932)
  - The method `TypeCode.get_compact_typecode` is defined as abstract. BEFORE: threw a `NO_IMPLEMENT` exception. Compatibility impact: Minimal impact for licensees, not for end user. Licensees need to provide a dummy implementation of this method. (CCC 4340932)
  - The mapping for the `get_interface_def(org.omg.CORBA.Object)` method in `org.omg.CORBA.portable.Delegate.java` is defined as abstract. Compatibility impact: Yes, a non-abstract method is converted to abstract. (CCC 4366071)
  - The mapping for the `write_Principal()` method in `org.omg.CORBA.portable.OutputStream.java` is no longer abstract. Compatibility impact: No, an abstract method is converted to non-abstract. (CCC 4366072)
  - The mapping for the `read_Principal()` method in `org.omg.CORBA.portable.InputStream.java` is no longer abstract. Compatibility impact: None, changing a method that is declared abstract to no longer be abstract does not break compatibility with pre-existing binaries. (CCC 4366074)

- To conform to the CORBA 2.3 specification, the `org.omg.DomainManagerOperations` interface no longer extends `org.omg.CORBA.Object`. Compatibility impact: None, no CORBA program will use the `DomainManagerOperations` interface directly. The `DomainManagerOperations` interface can only be used by the programs via the `DomainManager` interface, which already extends `org.omg.CORBA.Object`. (CCC 4340907)

- The following classes are declared as abstract and no longer have a private constructor. (CCC 4372196)

  `
  - org.omg.CORBA.ServiceDetailHelper
  - org.omg.CORBA.ServiceInformationHelper
  `

- To conform with the IDL to Java spec in section 1.15.2, the default constructor javadoc comments in the following `org.omg.CORBA` files have been changed from `COMPLETED_MAYBE` to `COMPLETED_NO`. Compatibility impact: None. (CCC 4363355)

  `
  - INTERNAL.java
  - INVALID_TRANSACTION.java
  - INV_OBJREF.java
  `

- The following Helper classes in `org.omg.CORBA` have been changed from `public final` to `public abstract`, and the default constructor for the Helper classes has been deleted. This change has been made to comply with the ORB core specification as defined by CORBA 2.3.1 and with the IDL/Java Language mapping as defined in ptc/00-01-08. Compatibility impact: Minimal since the Helper classes have been made 'abstract' as defined by the OMG IDL/Java Language mapping specification, applications which had previously instantiated a Helper class instance would fail. But the Helper class has only static methods in it, and there is no good reason for an application to create an instance of the Helper class. (CCC 4364208)

  `
  - AnySeqHelper.java
  - BooleanSeqHelper.java
  - CharSeqHelper.java
  - DoubleSeqHelper.java
  - FloatSeqHelper.java
  - LongLongSeqHelper.java
  - LongSeqHelper.java
  - OctetSeqHelper.java
  - ShortSeqHelper.java
  - StringValueHelper.java
  - ULongLongSeqHelper.java
  - ULongSeqHelper.java
  - UShortSeqHelper.java
  - WCharSeqHelper.java
  - WStringValueHelper.java
  `

- To conform with the recently passed OMG issue 3015, which adds a new class, `AbstractInterfaceDef` to Interface Repository classes, we have added the following new constants to `org.omg.CORBA.DefinitionKind`. Compatibility impact: None. (CCC 4367601)

  - `_dk_AbstractInterface=24`. This is a constant that indicates that an Interface Repository object is representing an abstract object.
  - `public static final DefinitionKind dk_AbstractInterface = new DefinitionKind(_dk_AbstractInterface)`. This is the static instance of `DefinitionKind`, indicating that an Interface Repository object represents an abstract interface.

- The following `org.omg.CORBA` APIs for typecodes were changed to conform to the OMG specification. All of the classes in the following list are in the `org.omg.CORBA` package. Compatibility impact: Yes. See each change below for details. (CCC 4368800)

  - The `Typecode` methods `fixed_digits`, `fixed_scale`, `member_visibility`, `type_modified`, and `concrete_base_type` are changed from concrete to abstract. Typecode is always implemented by an ORB implementor and never subclassed by an ORB user, so this should not impact customers.
  - `TCKind.from_int` no longer throws the unchecked exception `BAD_PARAM`. Since `BAD_PARAM` is an unchecked exception, removing the exception should not affect customer code at compile time.
  - `Principal` is changed to a concrete class with methods that throw `NO_IMPLEMENT` from an abstract class with abstract methods. `Principal` is deprecated and rarely used. In any case, it would not generally be subclassed by a user and would always be fully implemented by an ORB implementor.
  - An `extract_Streamable` method is added to `Any`. Adding a method does not affect compatibility.
  - `Any.insert_object( object, Typecode )` is changed to throw `BAD_PARAM`. Since `BAD_PARAM` is an unchecked exception, adding the exception should not affect customer code at compile time.
  - The `Any` methods `insert_Streamable`, `extract_Principal`, and `insert_Principal` are no longer abstract. `Any` is fully implemented by ORB implementors and never subclassed by ORB users, so this should not impact customers.
  - The `Any` methods `extract_value` and `insert_value` are changed to abstract. `Any` is fully implemented by ORB implementors and never subclassed by ORB users, so this should not impact customers.

- The `Identifier` field is added to `org.omg.CORBA.Initializer`. Compatibility impact: None. (CCC 4372194)

- To comply with ptc/00-01-08.pdf, the following classes are changed:

  - `org.omg.CORBA.ORBPackage.InvalidName.java` is declared as final. Compatibility impact: Yes. The `InvalidName` is being declared as final, which would impact source code that was subclassing this. Since it is an exception type, we do not anticipate this kind of behavior. (CCC 4366734)
  - `org.omg.stub.java.rmi._Remote_Stub.java` returns a clone of `_type_ids`. This will prevent mangling of the original `type_ids_` array by external users. (CCC 4366734)
  - The `from_int(Int i)` method in `org.omg.CORBA.SetOverrideType` no longer throws a `BAD_PARAM` exception. Compatibility impact: No. Should not cause a compatibility problem since we are removing a throws declaration of an unchecked exception. (CCC 4369490)
  - The `from_int(Int i)` method in `org.omg.CORBA.DefinitionKind` no longer throws a `BAD_PARAM` exception. Compatibility impact: No. (CCC 4370659)
  - `org.omg.CORBA.DynamicImplementation` has been deprecated by the OMG in favor of the Portable Object Adapter (POA). A default invoke body is supplied. Compatibility impact: No. Should not impact anyone implementing this class. (CCC 4369490)

- The following classes are changed to correct errors. Compatibility impact: No (CCC 4362556)
  - Helper and Holder classes are added to `UnknownUserException.java`. No compatibility impact.
  - Helper and Holder classes are added to `WrongTransaction.java`, and the class is declared final. No compatibility impact.
  - `CompletionStatus.java` is declared final, no longer implements `IDLEntity`, is changed to a private constructor. A `BAD_PARAM RuntimeException` will no longer explicitly be thrown by `from_int`. Compatibility impact: Yes. New code written using the new `CompletionStatus.java` class will not have to explicitly catch the `BAD_PARAM` runtime exception. If it's recompiled with an older JDK, it would get a compile-time error. -- These changes were undone due to JCK regression (4375061). An OMG issue has been filed instead (http://www.omg.org/issues/java-rtf.html#Issue3946).
  - `INV_POLICY.java` is declared as final. No compatibility impact.

- The addition of portable interceptors requires a new method on existing CORBA APIs and four new classes generated from IDL typedefs. Compatibility impact: none, these changes are all additions. (CCC 4379826)

  - `register_initial_reference` is added in `public class org.omg.CORBA.ORB`.
  - New class `org.omg.CORBA.StringSeqHelper` is added for 2 IDL typedefs.
  - New class `org.omg.CORBA.StringSeqHolder` is added for 2 IDL typedefs.
  - New class `org.omg.CORBA.WStringSeqHelper` is added for 2 IDL typedefs.
  - New class `org.omg.CORBA.WStringSeqHolder` is added for 2 IDL typedefs.

## API changes to javax.rmi.CORBA

To comply with OMG API specifications, the following changes have been made to `javax.rmi.CORBA`:

- The protected constructor in `javax.rmi.CORBA.Stub` is removed. Compatibility impact: None. (CCC 4366722)
- To comply with OMG specification 00-01-06.pdf, the `jaxax.rmi.CORBA.ClassDesc` constructor is removed. (CCC 4366734)

## Non-API changes

The following non-API changes were also implemented in JDK 5.0.

- Correct repository id computations. Compatibility impact: Yes. Added ORB versioning support to allow interoperability with the JDK 1.3 ORB, maintain backwards compatibility, and enable interoperability with other vendor ORBs. (CCC 4365188)

- To conform with the recently passed OMG issue 3015, we have taken all Interface Repository-related version pragmas out of `org.omg.CORBA.ir.idl`. This also changes the Repository ID values of a few IR interfaces that we ship in `org.omg.CORBA`, for example, `IDLTypeHelper`, from

  `private static String _id = "IDL:omg.org/CORBA/IDLType:2.3";`
  to
  `private static String _id = "IDL:omg.org/CORBA/IDLType:1.0";`

  Compatibility impact: Yes. This change might affect interoperability with existing implementations. Restart the application and the IR if you get a `COMM_FAILURE` exception (or something similar). (CCC 4372718)

- Added `@serial exclude` tags to all org.omg.* package files so that JAVADOC will ignore the whole package for the Serialization spec. There is no requirement from Object Management Group (OMG) to have Serialization compatibility between different versions. Practically speaking there are no use cases where the `org.omg` classes will be serialized in one version and de-serialized in the next version. Compatibility impact: None. (CCC 4394004)

- Changed `idlj` compiler arguments in support of POA, which is a new CORBA feature in Merlin. Changes to the `idlj` tool arguments include:

  - removed undocumented `-poa` flag
  - enabled generation of standard POA-based skeletons by default
  - added a new flag, `-oldImplBase`, to allow generation of backward compatible skeletons (compatible with JDK 1.2 and 1.3)

  Compatibility impact: Yes, existing programs that use the compiler may need to add the `-oldImplBase` flag to their `idlj` invocation to maintain compatibility. (CCC 4407835)

## New API

The following new API were added to JDK 5.0.

- The `PortableInterceptor` API is added. An incorrect specification, ptc/2000-04-05, was being referenced in the test plan. Another incorrect specification, orbos/99-12-02 was being referenced in the feature list (ptc/2000-04-05 is the same as orbos/99-12-02 except the format has changed). The correct specification reference for this new API is http://www.omg.org/cgi-gin/doc?ptc/2001-03-04. CCC 4307834 includes the list of changes/additions from ptc/2000-04-05. Compatibility impact: none, this is a new feature so no existing code uses it.

- The addition of portable interceptors requires a new method, `id`, in public interface `org.omg.PortableServer.POA`.

# Official Specifications for CORBA support in J2SE 5.0

## Specification References

The specifications with which the Java 2 Platform Standard Edition (J2SE) 5.0 ORB complies are as follows. If these links do not take you to the referenced specification, the OMG may have changed the URL, and you can link to www.omg.org to search for the correct specification.

- CORBA 2.3.1 (formal/99-10-07)
- IDL to Java language mapping (ptc/00-01-08)
- Revised IDL to Java language mapping (ptc/00-11-03)
- Java to IDL language mapping (ptc/00-01-06)
- Interoperable Naming Service (ptc/00-08-07)
- Portable Interceptors (ptc/2001-08-31)

These are the only specifications referenced by this document.

## Supported Specification Details

Not all of the above specifications are currently implemented in the ORB in J2SE 5.0. The precise list of supported sections is as follows:

- CORBA 2.3.1 chapters 1-3 and 6-9
- Revised IDL to Java language mapping, section 1.21.8.2, the `orb.properties` file.
- CORBA 2.3.1 chapter 4 with the following replacements from the Portable Interceptors specification:

- section 4.2.3.5 `destroy`
- section 4.5.2 `CodeFactory` and `PICurrent` are required
- Section 4.5.3.4 as updated for `register_initial_reference`

- CORBA 2.3.1 chapter 5 with the following update from the Portable Interceptors specification:

- 5.5.2 `StringSeq` and `WStringSeq` are required. This adds the following classes to `org.omg.CORBA`:

- `StringSeqHolder`
- `StringSeqHelper`
- `WStringSeqHolder`
- `WStringSeqHelper`

- CORBA 2.3.1 sections 10.6.1 and 10.6.2 are supported for repository IDs.
- CORBA 2.3.1 section 10.7 for `TypeCode` APIs.
- CORBA 2.3.1 chapter 11, Portable Object Adapter (POA), with the following updates from the Portable Interceptors specification:

- Section 11.3.7 POAs must preserve all policies
- Section 11.3.8.2 again states that POAs must preserve all policies
- Section 11.3.8.26 POA::id is required.

- CORBA 2.3.1 chapters 13 and 15 define GIOP 1.0, 1.1, and 1.2. The J2SE 5.0 ORB fully supports all versions of GIOP, with the exception that the bi-directional GIOP feature defined in sections 15.8 and 15.9 is not supported.
- All of the Interoperable Naming Service is supported.
- Portable Interceptors section 13.8 (the new `Coder`/`Decoder` interfaces) and all of chapter 21 (the interceptor specification).
- Section 1.21.8 of the Revised IDL to Java Language Mapping Specification (ptc/00-11-03) has been changed from the version in the IDL to Java Language Mapping Specification (ptc/00-01-08).

## Tools

- The IDL to Java compiler (`idlj`) complies with:

- CORBA 2.3.1 chapter 3 (IDL definition)
- CORBA 2.3.1 chapters 5 and 6 (semantics of Value types)
- CORBA 2.3.1 section 10.6.5 (pragmas)
- The IDL to Java mapping specification
- The Revised IDL to Java language mapping specification section 1.12.1 "local interfaces"

- The Java to IDL compiler (the IIOP backend for rmic) complies with:

- CORBA 2.3.1 chapters 5 and 6 (value types)
- The Java to IDL language mapping. Note that this implicitly references section 1.21 of the IDL to Java language mapping
- IDL generated by the -idl flag complies with CORBA 2.3.1 chapter 3.

# Other Compatibility Information

- The class `java.util.Calendar` is not interoperable between J2SE 1.3.x and J2SE 5.0 when using RMI-IIOP. OMG issue 3151 may resolve this, but it will probably have to be implemented in a later release of the Java platform.

  The J2SE 5.0 version of `Calendar` writes a `ZoneInfo` object in its `writeObject` method. Similarly, it calls `readObject` to read this. Based on Java Object Serialization, it expects that if it's talking to an older version, the object won't be there, so the stream will throw an `EOFException` and keep the stream position intact.

Copyright © 2001-2004 Sun Microsystems, Inc. All Rights Reserved. | Java Software