======================================================================
Release notes for Ice 3.3.0
======================================================================

The sections below describe the new features and fixes included in
this release. See the section titled "Upgrading your application"
for more information about migrating to a new Ice release, including
details about APIs that have been deprecated or removed in this
release.

Note that because the Python, Ruby, and PHP language mappings use the
C++ Ice run time, they automatically benefit from fixes to the C++ Ice
core even if those language mappings are not explicitly mentioned
below.


Table of Contents
-----------------

  1. New Features
     - Non-blocking AMI
     - Scalability improvements in Glacier2
     - IceStorm
     - Freeze transactional evictor
     - Administrative facility
     - Dynamic network interfaces
     - IPv6 and UDP multicast
     - Updated C# mapping
  2. Ice for .NET
  3. Fixes and improvements
  4. Desupported components
     - Java2
     - Thread per connection concurrency model
  5. Upgrading your application
     - Migrating IceStorm databases
     - Migrating IceGrid databases
     - Removed APIs
     - Deprecated APIs
  6. Platform specific notes
     - IBM JDK
     - Java and IPv6
     - Mono
     - Red Hat Enterprise Linux 5.1
     - Solaris x86


======================================================================
1. New Features
======================================================================

This section discusses the significant enhancements offered in this
release.


Non-blocking AMI
----------------

Ice 3.3 includes an important change in the semantics of AMI
requests: Ice now guarantees that the calling thread will never block
when issuing an asynchronous invocation.

In previous releases, the Ice run time blocked the calling thread
until the request was accepted by the local transport buffer.
Typically this occurred quickly enough that AMI requests appeared to
be non-blocking, and applications may have been designed based on that
assumption. In fact, however, there were many opportunities for an AMI
request to block:

* If a connection was not yet established, the calling thread would
  block while Ice attempted to resolve DNS host names and open a
  connection to one of the proxy's endpoints.

* When using an indirect proxy, the calling thread blocked while Ice
  issued a request to the locator.

* If the local network buffer was full, Ice blocked until there was
  room for the entire message.

An application could use timeouts to avoid blocking indefinitely, but
it was not safe to assume that an AMI request would never block.

As of this release, Ice behaves quite differently when processing an
AMI request. An initial attempt is made to send the request
synchronously, without blocking. This includes the activities
mentioned above, such as establishing a connection and contacting a
locator. If any of these activities would block, Ice queues the
request and returns immediately. Queued requests are sent in the
background; in C++ and Java, an internal thread performs this duty,
while in .NET Ice uses the platform's asynchronous I/O facility.

An application can still use timeouts if necessary, and in fact
AMI timeouts have much greater precision in this release because they
no longer depend on the interval defined by the configuration property
Ice.MonitorConnections.

The new non-blocking nature of AMI requests is especially useful for
a graphical application, which in previous releases needed to use some
potentially elaborate workarounds to avoid impacting the interactive
responsiveness of its user interface.

Along with this new capability comes new responsibility. There now
exists the potential for accumulating an unlimited number of queued
AMI requests in the Ice run time, consuming an equally unlimited
amount of memory. To that end, Ice provides new APIs that enable an
application to implement its own flow-control logic:

* Asynchronous proxy methods now return a boolean value to indicate
  whether the AMI request was sent synchronously. If the method
  returns false, it means the Ice run time has queued the request.

* An AMI callback can be notified when a queued request is sent.

Taken together, these two API enhancements allow you to keep track of
your outstanding AMI invocations.

There have been other notable changes to the asynchronous invocation
model:

* AMI now supports oneway requests. The callback object is required
  to implement the ice_response and ice_exception methods as usual,
  but ice_response is not called for oneway requests. Ice calls the
  ice_exception method if an error occurs before a oneway request
  is accepted by the local transport buffer.

* Batch requests can be flushed for individual proxies using two new
  proxy methods:

  void ice_flushBatchRequests()
  bool ice_flushBatchRequests_async(callback)

  As its name implies, the second method allows you to flush batch
  requests with non-blocking AMI semantics.

* Ice guarantees that the thread making an AMI request is never used
  to invoke a method in the callback object. Instead, all invocations
  on an AMI callback are now performed by a thread from an Ice thread
  pool. As a result, it is now safe to hold a non-recursive lock while
  making an AMI request, whereas in previous releases doing so had the
  potential for causing a deadlock if the callback acquired the same
  lock.

* A thread that invokes an asynchronous proxy method must be prepared
  to catch CommunicatorDestroyedException if it is possible for the
  communicator to be destroyed while the thread is active. All other
  exceptions are passed to the ice_exception method of the callback
  object. This behavior differs from previous releases, in which no
  exceptions could be raised by an asynchronous proxy method.

Please refer to the "Asynchronous Programming" chapter in the Ice
manual for more information on the new AMI semantics.


Scalability improvements in Glacier2
------------------------------------

The new AMI semantics made it possible to significantly improve the
scalability of the Glacier2 router. In previous releases Glacier2 used
the thread-per-connection concurrency model in an effort to prevent
the activities of one client from impacting other clients. The main
disadvantage of using thread-per-connection is that it did not scale
as well as the thread pool concurrency model.

Glacier2 now uses the thread pool for greater scalability, and takes
advantage of non-blocking AMI to ensure that slow or misbehaving
clients cannot affect the router's other clients.

The router's buffering mode has also been enhanced so that at most
two threads are used, rather than a thread for each client as in prior
versions. However, it is no longer necessary to use buffered mode
solely to gain better separation between clients; Glacier2 now
provides the same separation regardless of its buffering mode. The
primary motivations for enabling buffering are to give the router an
opportunity to batch oneway requests, and to support its ability to
override pending requests.


IceStorm
--------

The most significant improvement to IceStorm is the addition of a
highly-available mode. Using master-slave replication with support for
automatic failover, IceStorm now provides a much greater degree of
reliability. This mode is enabled entirely via configuration and
requires no changes to publishers or subscribers.

This release also contains a number of other IceStorm changes:

* Subscriptions are now persistent by default, meaning IceStorm stores
  the proxy of each subscriber in its database. At startup, IceStorm
  considers each of these subscribers as already subscribed and
  automatically removes a subscriber's proxy from the database if a
  delivery attempt fails. To take advantage of a persistent
  subscription, a subscriber should register either an indirect proxy
  or a direct proxy that uses a fixed port.

* A new Quality of Service (QoS) parameter, retryCount, gives a
  subscriber some control over IceStorm's behavior when delivery
  attempts fail.

* IceStorm can run in a fully-transient mode in which no databases are
  maintained. Replication is not supported in this mode.

* IceStorm guarantees that it will deliver all received events to
  subscribers before it shuts down.

* A new operation, getNonReplicatedPublisher, has been added to the
  Topic interface for use when event ordering is important.

The IceStorm chapter in the Ice manual has more information on these
changes, including a new section devoted to the highly-available mode.


Freeze transactional evictor
----------------------------

This release adds a new kind of Freeze Evictor in which all write
operations are automatically enclosed in a Freeze transaction. This
new Evictor gives applications write-ordering guarantees, allows
developers to enclose several operations in the same transaction (when
using collocated invocations), and helps ensure data consistency when
recovering from a crash.

See the "Freeze" chapter in the Ice manual for complete details.


Administrative facility
-----------------------

Ice supports an extensible new facility for adding administrative
capabilities to your applications. When an application is properly
configured, the Ice run time creates a dedicated object adapter that
hosts a single object known as the "admin" object. Each administrative
capability is represented by a separate facet of the admin object.

Ice supplies two facets by default: the Process facet enables a server
activation service such as IceGrid to gracefully terminate the
process, and the Properties facet allows remote inspection of a
program's configuration. Applications can also install their own
facets, and easily control which facets are enabled using a
configuration property.

IceBox extends the facility to make its ServiceManager interface
available via an administrative facet, giving you the ability to
remotely start and stop individual IceBox services. The facility is
also integrated into IceGrid and its administrative clients. You can
find more details in the relevant chapters of the Ice manual.

For more information on the administrative facility, see the "Ice
Run Time" chapter.


Dynamic network interfaces
--------------------------

Ice server endpoints that are configured to listen on all local
interfaces now listen on INADDR_ANY/0.0.0.0 rather than listening
separately on each of the interfaces that were found at the time the
server started. This means that if a new interface becomes available
while the server is running, Ice will be able to receive and process
requests using that interface.

Note that, if an interface change occurs, an object adapter does not
automatically refresh the list of endpoints that it embeds in newly-
created proxies. Rather, an application must instruct the object
adapter to refresh its endpoint list using the new operation
refreshPublishedEndpoints. See the "Ice Run Time" chapter in the Ice
manual for further details.


IPv6 and UDP multicast
----------------------

Ice 3.3 includes support for IPv6 as well as UDP multicast. Both of
these features are controlled via configuration properties.

IPv6 is disabled by default, and can be enabled using the new property
Ice.IPv6. Another new property, Ice.IPv4, allows you to disable the
use of IPv4 if you prefer to use only IPv6 in your application.

Using UDP multicast in an application simply requires that you select
an appropriate IP address for your endpoints.

Appendix D of the Ice manual explains the syntax for specifying IPv6
and UDP multicast addresses in endpoints.


Updated C# mapping
------------------

New metadata allows .NET users to map Slice sequence types into
generic .NET 2.0 collections:

  // Slice
  ["clr:generic:List"] sequence<int> S;

maps to:

  // C#
  System.Collections.Generic.List<int> S;

Additional collection types are also supported.

Slice dictionary types now map to a generic .NET 2.0 collection by
default:

  // Slice
  dictionary<string, int> D;

maps to:

  // C#
  System.Collections.Generic.Dictionary<string, int> D;

If you prefer to use the previous .NET 1.1 mapping to DictionaryBase,
you will need to annotate your Slice definitions with the metadata
tag "clr:collection".


======================================================================
2. Ice for .NET
======================================================================

Given the language-neutral nature of .NET's Common Language Runtime
(CLR), maintaining Slice compilers for both Visual Basic and C# is
unnecessary. As a result, Ice no longer includes a Slice compiler for
Visual Basic, and Ice for C# is now known as Ice for .NET.

Users can write an Ice application in any language that is supported
by the CLR, but Slice definitions must now be generated in C#.

The names of the Ice for .NET run-time DLLs have also been changed
accordingly. Below is a list of the old DLL names and their equivalent
names in this release:

  icecs.dll        Ice.dll
  glacier2cs.dll   Glacier2.dll
  iceboxcs.dll     IceBox.dll
  icegridcs.dll    IceGrid.dll
  icepatch2cs.dll  IcePatch2.dll
  icesslcs.dll     IceSSL.dll
  icestormcs.dll   IceStorm.dll

You will need to update your Visual Studio projects to reflect these
changes. Ice continues to include sample programs for Visual Basic,
and you can use these projects as a guide for updating your own Visual
Basic projects.


======================================================================
3. Fixes and improvements
======================================================================

Below is an abbreviated list of changes included in this release that
were not already discussed in "New Features". For a complete list of
changes, please refer to the CHANGES file included in your Ice
distribution.

* An IceBox service can now recursively start and stop other IceBox
  services from within its start and stop methods. The level of
  recursion is limited to the threads in the administrative object
  adapter's thread pool.

* IceBox services that share a communicator now use a dedicated
  communicator instance that is not used by the IceBox server. This
  dedicated communicator only inherits properties from the server's
  communicator if IceBox.InheritProperties is set to a non-zero value.

* It is no longer necessary to define a value for the property
  IceBox.ServiceManager.Endpoints. If this property is not defined,
  the ServiceManager interface is not available.

* Configuration properties for IceBox services can now be defined on
  the command line.

* A new object adapter property, <adapter>.ProxyOptions, lets you
  customize the proxies that the adapter creates.

* Accepting incoming connections can no longer block a thread from a
  server thread pool. This includes activities such as connection
  validation and SSL handshaking.

* The new property Ice.TCP.Backlog allows you to specify the size of
  incoming connection backlog for TCP/IP sockets. This setting is
  also used for SSL. In C++ the default value is SOMAXCONN or 511 if
  that macro is not defined. In Java and .NET the default value is
  511.

* Changed servant locators so both locate() and finished() can throw
  user exceptions.

* It is now legal to change the compression setting of a fixed proxy.

* An IceGrid node is more conservative when removing the directory of
  a server. The node only removes the directory when the server is
  explicitly removed from a deployed application or if the directory
  contains only files and directories that were created by the node.

* IceGrid's round-robin load balancing policy better handles servers
  that are unreachable.

* When resolving the endpoints of a replica group, the IceGrid locator
  no longer waits for an object adapter to complete its activation if
  another adapter is already active.

* Added an object adapter to the IceGrid registry. The adapter is
  named `IceGrid.Registry.AdminSessionManager' and is responsible for
  Glacier2 administrative sessions.

* Glacier2 filters are now disabled by default for IceGrid client
  and administrative sessions created with the IceGrid session
  managers. If you rely on these filters being enabled, you must now
  explicitly set the property IceGrid.Registry.SessionFilters or
  IceGrid.Registry.AdminSessionFilters.

* The IceGrid node now unblocks the SIGHUP, SIGINT and SIGTERM signals
  from forked servers.

* Several improvements have been made to the output of slice2html.

* The inheritance structure of C++ servant classes has changed such
  that it is now possible for a servant to derive from
  IceUtil::Thread.

* If a proxy contains a host that is multihomed, the client will now
  try all of the IP addresses reported by DNS. Previously, only the
  first address in the list was used and others were ignored.

* The way that the Ice run time determines whether a proxy invocation
  is eligible for collocation optimization has changed somewhat. The
  Ice run time no longer performs a DNS lookup; instead, invocations
  on a direct proxy will use the optimization only if the host and
  port of one of its endpoints match the host and port of an endpoint
  or published endpoint of an object adapter from the same
  communicator.

* Exceptions thrown from collocation-optimized invocations are now
  fully transparent. If an operation throws an exception that is
  not in the operation's exception specification, or throws a
  non-Ice exception, the client receives UnknownUserException
  or UnknownException, exactly as if the servant for a remote
  invocation had thrown the same exception. (In earlier versions,
  the client received the original exception, rather than an
  unknown exception.)

  For Ice run-time exceptions, all run-time exceptions are passed
  to the client as UnknownLocalException, except for

  - ObjectNotExistException
  - FacetNotExistException
  - OperationNotExistException
  - OperationNotExistException
  - UnknownException
  - UnknownLocalException
  - UnknownUserException
  - CollocationOptimizationException

* Most proxy factory methods now return a proxy of the same type as
  the original and no longer require the use of a checked or unchecked
  cast. For example, in C++ you can write

  HelloPrx hello = ...;
  hello = hello->ice_oneway();

  Previously you would have needed a cast, such as

  hello = HelloPrx::uncheckedCast(hello->ice_oneway());

  In Java and .NET, you must use a type cast:

  hello = (HelloPrx)hello.ice_oneway();

* The IceSSL plugins for Java and .NET now support a password callback
  interface. You can also specify the class name of a certificate
  verifier or password callback via configuration properties.

* It is now possible to use Ice's built-in sequence types in Slice
  data structures that are compiled with streaming support. Previously
  this would not work because the Ice sequences were not compiled with
  streaming support.

* Changed Ice.Exception in .NET to derive from System.Exception
  instead of System.ApplicationException in accordance with
  Microsoft's recommendations for writing custom exceptions.

* The Ice.Application class now supports signal handling on Mono.

* The .NET build system supports the new macro MANAGED, which can be
  enabled if you want to build a version of the Ice run time that uses
  only managed code.

* Marshaling performance in .NET has been improved.

* The rules for legal property names and values have been relaxed.
  Refer to the "Properties" chapter in the Ice manual for a complete
  description of the syntax. The limit on the line length of a
  property in a configuration file has also been removed.

* The new property Ice.Warn.UnusedProperties causes the communicator
  to display a warning during its destruction that lists all
  properties that were set but whose values were never read.

* Ice for Java now supports the ICE_CONFIG environment variable.

* It is now possible to use UNC paths on Windows in the configuration
  of Ice services.

* A string converter plugin has been added to Ice for C++, which is
  particularly useful for the scripting language extensions.

* Ice for Python now accepts Unicode objects as arguments to remote
  operations.


======================================================================
4. Desupported components
======================================================================

This section describes Ice components that are no longer supported.


Java2
-----

Ice for Java now requires Java5 or Java6 as its compilation and run-
time environment. See the section titled "Deprecated APIs" for
additional information on the Java language mapping.

To continue using Java2 for your application, you must use a previous
Ice release. Note however that ZeroC only provides support for the
most recent Ice release unless you have a support contract.


Thread per connection concurrency model
---------------------------------------

The improvements introduced by the non-blocking AMI feature (see
"Background I/O") have made this concurrency model unnecessary
and it has been removed as of this release. See "Removed APIs" for
additional information.


======================================================================
5. Upgrading your application
======================================================================

Ice 3.3 does not maintain backward binary compatibility with
applications built using Ice 3.2, but every effort was made to
preserve source compatibility. Note however that Ice always maintains
protocol ("on the wire") compatibility with prior releases.

The requirements for upgrading depend on the language mapping used by
your application:

- For statically-typed languages (C++, Java, .NET), the application
  must be recompiled.

- For scripting languages that use static translation, your Slice
  files must be recompiled.

If your application uses IceStorm or IceGrid, please refer to the
relevant sections below for migration instructions.

Finally, certain APIs that were deprecated in previous Ice releases
have been removed in this release. If your application relied on one
of these APIs, it may no longer compile or execute correctly. A list
of the removed APIs is provided in the section titled "Removed APIs"
along with a description of their replacements. Furthermore, the
section "Deprecated APIs" discusses APIs that are deprecated as of
this release; we encourage you to update your applications and
eliminate the use of these APIs as soon as possible.


Migrating IceStorm databases
----------------------------

Ice 3.3 supports migrating IceStorm databases from Ice 3.1 and from
Ice 3.2. Migration from other Ice versions may work, but is not
officially supported. If you require assistance with this please
contact sales@zeroc.com.

To migrate, first stop your IceStorm servers.

Next, copy the IceStorm database environment to a second location:

$ cp -r db recovered.db

Run the Berkeley DB utility db_recover on the copied database
environment:

$ db_recover -h recovered.db

Note that it is essential that the correct version of db_recover is
used. For Ice 3.1, Berkeley DB 4.3.29 must be used. For Ice 3.2,
Berkeley DB 4.5 must be used.

Now change to the location where the Ice 3.3 IceStorm database
environments are stored:

$ cd <new-location>

Next, run the icestormmigrate utility. The first argument is the path
to the old database environment. The second argument is the path to
the new database environment.

In this example we'll create a new directory "db" in which to store
the migrated database environment:

$ mkdir db
$ icestormmigrate <path-to-recovered.db> db

The migration is now complete, and the contents of the old database
environment are now in the db directory.


Migrating IceGrid databases
---------------------------

Ice 3.3 supports migrating IceGrid databases from Ice 3.1 and from Ice
3.2. Migration from other Ice versions may work, but is not officially
supported. If you require assistance with this please contact
sales@zeroc.com.

To migrate, first stop the IceGrid registry you wish to upgrade.

Next, copy the IceGrid database environment to a second location:

$ cp -r db recovered.db

Run the Berkeley DB utility db_recover on the copied database
environment:

$ db_recover -h recovered.db

Note that it is essential that the correct version of db_recover is
used. For Ice 3.1, Berkeley DB 4.3.29 must be used. For Ice 3.2,
Berkeley DB 4.5 must be used.

Now change to the location where the Ice 3.3 IceGrid database
environments are stored:

$ cd <new-location>

Next, run the upgradeicegrid.py utility located in the `config'
directory of your Ice distribution (or in /usr/share/Ice-3.3.0 if using
an RPM installation). The first argument is the path to the old
database environment. The second argument is the path to the new
database environment.

In this example we'll create a new directory "db" in which to store
the migrated database environment:

$ mkdir db
$ upgradeicegrid.py <path-to-recovered.db> db

The migration is now complete, and the contents of the old database
environment are now in the db directory.

By default, the migration utility assumes that the servers deployed
with IceGrid also use Ice 3.3. If your servers still use an older Ice
version, you need to specify the --server-version command-line option
when running upgradeicegrid.py:

$ upgradeicegrid.py --server-version 3.2.1 <path-to-recovered.db> db

The migration utility will set the server descriptor `ice-version'
attribute to the specified version and the IceGrid registry will
generate configuration files compatible with the given version.

If upgrading the master IceGrid registry in a replicated environment
and the slaves are still running, you should first restart the master
registry in read-only mode using the --readonly option, for example:

$ icegridregistry --Ice.Config=config.master --readonly

Next, you can connect to the master registry with icegridadmin or the
IceGrid administrative GUI to ensure that the database is correct. If
everything looks fine, you can shutdown and restart the master
registry without the --readonly option.


Removed APIs
------------

This section describes features and APIs that are no longer available
in this release.

* Thread per connection

  The primary purpose of this concurrency model was to serialize the
  requests received over a connection, either because the application
  needed to ensure that requests are dispatched in the order they are
  received, or because the application did not want to implement the
  synchronization that might be required when using the thread pool
  concurrency model.

  Another reason for using the thread-per-connection concurrency model
  is that it was required by the IceSSL plug-ins for Java and C#. This
  requirement has been eliminated.

  The ability to serialize requests is now provided by the thread pool
  and enabled via a new configuration property:

  <threadpool>.Serialize=1

  Please refer to the "Ice Run Time" chapter of the Ice manual for
  more details on this feature.

  Aside from the potential semantic changes involved in migrating your
  application to the thread pool concurrency model, other artifacts of
  thread-per-connection may be present in your application and must be
  removed:

  - The configuration properties Ice.ThreadPerConnection and
    <proxy>.ThreadPerConnection

  - The proxy methods ice_threadPerConnection and
    ice_isThreadPerConnection

* .NET metadata

  The metadata directive "cs:collection" is no longer valid. Use
  ["clr:collection"] instead.

* C++

  The following methods have been removed:

  - Application::main(int, char*[], const char*, const Ice::LoggerPtr&)

    Use Application::main(int, char*[], const InitializationData&)
    instead.

  - initializeWithLogger
  - initializeWithProperties
  - initializeWithPropertiesAndLogger

    Use initialize(int, char*[], const InitializationData&) instead.

  - stringToIdentity
  - identityToString

    Use the equivalent Communicator operations.

* Java

  The following methods have been removed:

  - Application.main(String, String[], String, Logger)

    Use Application.main(String, String[], InitializationData)
    instead.

  - initializeWithLogger
  - initializeWithProperties
  - initializeWithPropertiesAndLogger

    Use initialize(String[], InitializationData) instead.

* .NET

  The following methods have been removed:

  - Application.main(string, string[], string, Logger)

    Use Application.main(string, string[], InitializationData)
    instead.

  - initializeWithLogger
  - initializeWithProperties
  - initializeWithPropertiesAndLogger

    Use initialize(ref string[], InitializationData) instead.

* Python

  The following methods have been removed:

  - initializeWithLogger
  - initializeWithProperties
  - initializeWithPropertiesAndLogger

    Use initialize(args, initializationData) instead.

  - stringToIdentity
  - identityToString

    Use the equivalent Communicator operations.

* General

  The following methods have been removed:

  - ice_hash
  - ice_communicator
  - ice_collocationOptimization
  - ice_connection

    These proxy methods were replaced by ones of the form ice_get...,
    such as ice_getHash. ice_collocationOptimization is now
    ice_getCollocationOptimized.

  - ice_newIdentity
  - ice_newContext
  - ice_newFacet
  - ice_newAdapterId
  - ice_newEndpoints

    These proxy methods were replaced by ones that do not use "new" in
    their names. For example, ice_newIdentity was replaced by
    ice_identity.

* Ice.LoggerPlugin

  This property provided a way to install a custom logger
  implementation. It has been replaced by a more generalized facility
  for installing custom loggers.


Deprecated APIs
---------------

The Ice APIs and components listed below are deprecated in this
release. They will be supported for at least one more minor release;
for example, these items will be supported in Ice 3.4 and removed in
Ice 3.5. We encourage you to update your applications and eliminate
the use of these APIs as soon as possible.

* Java2 language mapping

  Java5 is now the default language mapping. Applications that use the
  Java2 mapping can continue to use it by adding the appropriate
  metadata tag to your Slice files or by using the "--meta java:java2"
  option when running the Slice-to-Java compiler. Note that the
  compiler now emits a deprecation warning when it encounters the
  Java2 metadata tag.

  If you used the "java:java5" metadata tag when compiling your Slice
  definitions, you can now remove those tags. Any uses of custom type
  metadata ("java:type:...") should also be reviewed.

* Sequences as dictionary keys

  The use of sequences, and structures containing sequences, as the
  key type of a Slice dictionary is now deprecated.

* LocalObject

  The mappings for the LocalObject type have changed in Java, .NET and
  Python. The new mappings are shown below:

  Java    java.lang.Object
  .NET    System.Object
  Python  object

  The types Ice.LocalObject and Ice.LocalObjectImpl are deprecated.

* Ice.MonitorConnections

  In previous releases this property specified the interval at which a
  background thread in the Ice run time checked for idle connections
  and enforced timeouts on AMI requests. This setting is now ignored
  because the changes to AMI (see "New Features") include more precise
  AMI timeouts.

* Ice.Trace.Location

  This property has been replaced by Ice.Trace.Locator.

* Ice.Default.CollocationOptimization

  This property, as well as the corresponding proxy property, have
  been replaced by Ice.Default.CollocationOptimized and
  <proxy>.CollocationOptimized, respectively.

* <Adapter>.RegisterProcess

  This property caused the Ice run time to register a proxy with the
  locator registry (e.g., IceGrid) that allowed the process to be shut
  down remotely. The new administrative facility (see "New Features")
  has replaced this functionality.

* Ice.ServerId

  As with <Adapter>.RegisterProcess, this property was used primarily
  for IceGrid integration and has been replaced by a similar mechanism
  in the administrative facility (see "New Features").

* Glacier2.Admin
  IcePatch2.Admin

  These are the names of administrative object adapters in Glacier2
  and IcePatch2, respectively. The functionality offered by these
  object adapters has been replaced by that of the administrative
  facility (see "New Features"), therefore these adapters (and their
  associated configuration properties) are deprecated.


======================================================================
6. Platform specific notes
======================================================================


IBM JDK
--------

The IBM JDK ships with limited jurisdiction policy files for the
cryptographic libraries. This creates an issue for Ice's certificate
authority script (iceca) when running with the command-line options
"iceca java --import". The import fails with an error similar to:

  "java.lang.SecurityException: Unsupported keysize or algorithm
  parameters"

To solve this problem you must install the unlimited jurisdiction
policy files. For more information, including a link to download
the policy files, see:

  http://www.ibm.com/developerworks/java/jdk/security/50/

Once you have downloaded the policy files, you must unpack them into
the jre/lib/security directory.


Java and IPv6
-------------

IPv6 is not currently supported in Java on Windows due to a bug in the
JVM. Refer to the bug database for more information:

  http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6230761


Mono
----

Mono requires that a system's host name be correctly configured and
that it resolves to an IP address. Otherwise, Mono is unable to
determine the local IP addresses, which causes the creation of object
adapters that listen on INADDR_ANY/0.0.0.0 to fail with an
Ice::DNSException.


Red Hat Enterprise Linux 5.1
----------------------------

On Red Hat Enterprise Linux 5.1 systems, Ice connection establishment
to inactive ports of the IPv6 loopback address might hang instead of
immediately reporting "connection refused" (ECONNREFUSED). The hang
can last for several minutes and is similar to hangs you would get if
you try to connect to an unreachable address. We are still
investigating the exact cause of this hang but so far we believe this
is a Linux issue that occurs only with the IPv6 implementation of
RHEL 5.1.


Solaris 10 x86
--------------

C++ developers using sequence<bool> on Solaris 10 x86 (32-bit) should
link their applications with the static version of libCstd, or upgrade
the Sun C++ runtime shared libraries to a newer version (not yet
available as of this Ice release).

Refer to http://forum.java.sun.com/thread.jspa?threadID=5277939 for
more information.
