Ice-E 1.2.0 Release Notes
=========================


New Supported Platforms
-----------------------

The following operating systems are now supported for Ice-E:

 * Windows Mobile 5.0
 * Windows Mobile 6
 * Windows Vista
 * Gumstix Linux
 * SuSE Linux Enterprise Server 10

The following Java virtual machines are now supported:

 * NSIcom CrE-ME 4.12 (Java ME CDC 1.0 with PP 1.0)
 * Sun JDK/JRE 1.5
 * Sun JDK/JRE 1.6

For the complete list of supported platforms, please see

  http://www.zeroc.com/icee/platforms.html


Desupported Platforms
---------------------

Ice-E no longer supports the following operating systems:

 * Fedora Core 4 Linux
 * Windows 2000

The following C++ compilers are no longer supported:

 * eMbedded Visual C++ 4.0
 * Visual C++ 6.0
 * Visual Studio .NET 2003

For Java, we no longer support:

 * NSIcom CrEme 3.27 (Personal Java 3.1)
 * Sun JDK/JRE releases older than 1.4.2


API Changes - General
---------------------

- Added Communicator::propertyToProxy() which creates a proxy from
  a set of properties. This operation allows you to set various local
  proxy settings, such as the locator, which cannot be set using
  stringToProxy().

- Message batches are now automatically flushed when the total size of
  the batch reaches the message size maximum. This feature can be
  controlled using the Ice.BatchAutoFlush property, which is on by
  default.

- If a proxy does not specify a hostname (via -h HOST), the client
  only attempts to connect to the loopback interface (127.0.0.1).

- For object adapters without endpoints, Ice.Trace.Network >= 2 now
  prints a trace message.

- Added a new Slice metadata tag for operations. The ["nonmutating"]
  tag provides backward compatibility for idempotent operations that
  were previously declared using the deprecated 'nonmutating' keyword.
  You can replace the 'nonmutating' keyword with '["nonmutating"]
  idempotent' to maintain compatibility with objects implemented using
  earlier versions.

- Added the following proxy methods:

  ice_secure
  ice_isSecure
  ice_datagram
  ice_isDatagram
  ice_batchDatagram
  ice_isBatchDatagram
  ice_getAdapterId
  ice_adapterId 

  Note that the addition of these proxy methods does not imply that
  Ice-E now supports secure, datagram or batch datagram invocations; 
  TCP is still the only transport included with Ice-E.

- Attempts to change the attributes of a fixed proxy now result in a
  FixedProxyException rather than just ignoring the change request and
  returning the same proxy. Also, attempts to marshal a fixed proxy
  now result in a FixedProxyException rather than a MarshalException.

- Added destroy() operation to the ObjectAdapter interface. This
  operation must be called in order to reclaim the adapter's resources
  and be able to recreate a new adapter with the same name. Destroying
  a communicator automatically calls destroy on all of its adapters.

- Removed getDefaultProperties() functions, and the global default
  properties. If you need global properties, you can easily
  create your own global variable.

- Moved identityToString and stringToIdentity to the Communicator
  interface.

- Added new operation Communicator::createObjectAdapterWithRouter(),
  which creates a routed object adapter. An object adapter may now
  be associated with at most one router, which is defined using this
  operation or by setting the <AdapterName>.Router property. Also
  as a result of this change, the ObjectAdapter::addRouter() and
  ObjectAdapter::removeRouter() operations have been removed.

- Added communicator initialize functions that take an argument of
  type Ice::InitializationData. This structure contains communicator
  members that may only be set during communicator initialization.
  Currently included are Properties, Logger and string converters.
  The initializeWithXXX functions and the setLogger() operation have
  been removed.

- Removed most specializations of the Ice::ProtocolException local
  exception to reduce code size. Only the following specializations
  were kept:

  Ice::CloseConnectionException
  Ice::ForcedCloseConnectionException
  Ice::MarshalException
  Ice::MemoryLimitException

  The reason for the protocol error is now provided in the 'reason'
  member of Ice::ProtocolException.

- Removed the communicator's support for default contexts. An
  application that passes a context during a proxy invocation can
  either specify the context as an explicit argument, or use the
  ice_context proxy method to establish a default context for a proxy.

- Removed support for local interfaces in Slice.


API Changes - C++ Only
----------------------

- Added a new Slice metadata tag for operations. The ["cpp:const"] tag
  generates a const member function on the corresponding servant base
  class.

- All Ice exceptions now derive from std::exception, so a single catch
  handler can be used for Ice exceptions:

  try
  {
      // Call something that may throw an Ice exception
  }
  catch(const ::std::exception& ex)
  {
      cerr << ex.what() << endl; // Works for any ::std::exception,
                                 // including Ice exceptions
  }

  what() is implemented in terms of toString(), so overriding
  toString() also changes the string returned by what().

- The ice_name() member function of exceptions derived from
  Ice::Exception (and, hence, IceUtil::Exception) now returns a
  non-const string instead of a const string:

  const ::std::string ice_name() const; // Old signature

  ::std::string ice_name() const; // New signature

- For non-abstract Slice classes, the generated C++ code now has a
  protected destructor. This prevents accidental allocation of
  class instances on the stack or as static variables. For the
  implementation of abstract Slice classes and for servant classes
  applications can do the same thing and add a protected destructor
  to prevent non-heap allocation.

- Added ability to configure user-defined string and wstring
  converters that are used during marshalling/unmarshalling to
  convert between UTF-8 (as required by the Ice protocol) and the
  user's character set.

  A custom narrow string converter must derive from the class
  Ice::StringConverter, and a wide string converter must derive
  from Ice::WstringConverter. The converter objects are supplied as
  members of the Ice::InitializationData structure that is passed
  to Ice::initialize().

- Added support for the new Slice metadata tag ["cpp:type:wstring"],
  which generates code to use std::wstring instead of std::string.

- The signature of createProperties(argc, argv) is now:

  PropertiesPtr createProperties(int* argc, char* argv[],
                                 const PropertiesPtr& defaults = 0,
                                 const StringConverterPtr& conv = 0);

  where "defaults" represents an optional set of default properties
  used to initialize the new Properties object. Ice properties
  defined on the command line and properties defined in a
  configuration file override these default properties.

  If a string converter is supplied, it is only invoked when a program
  calls the Properties::load operation. Each key and value in the
  property file is passed to the converter.


API Changes - Java Only
-----------------------

- Added new createProperties() methods:

  public static Properties
  createProperties(StringSeqHolder args, Properties defaults)

  public static Properties
  createProperties(String[] args, Properties defaults)

  "defaults" represents an optional set of default properties
  used to initialize the new Properties object. Ice properties
  defined on the command-line and properties defined in the Ice
  config file may override these default properties.