======================================================================
Release notes for Ice 3.4.1
======================================================================

Introduction
------------

This document outlines changes and improvements in this release that
may affect the operation of your applications or have an impact on
your source code. Refer to the "Upgrading" sections for more
information about migrating to a new Ice release.

For a detailed list of the changes in this release, please refer to
the CHANGES file included in your Ice distribution.


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

  1. New Features
     - Changes and fixes in Ice 3.4.1
     - Features added with Ice 3.4.0
  2. Upgrading your application from Ice 3.4.0
     - RPMS
     - Windows
     - Binary Archives
     - Source Distribution
     - Deprecated APIs
  3. Upgrading your application from Ice 3.3
     - Compatibility
     - Java language mapping changes
     - Changes to the Java API for Freeze maps
     - Freeze packaging
     - PHP changes
     - IceSSL changes
     - Thread pool changes
     - Migrating IceStorm and IceGrid databases
     - Migrating Freeze databases
     - Removed APIs
     - Deprecated APIs
  4. Upgrading your application from Ice 3.2 or earlier releases
     - Migrating IceStorm databases
     - Migrating IceGrid databases
     - Migrating Freeze databases
     - Removed APIs
     - Deprecated APIs
  5. Platform-specific notes
     - Supported platforms
     - Java and IPv6
     - Mono
     - IBM JDK
  6. Known Problems
     - iceca failure on SLES11


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

This section discusses the significant enhancements in Ice 3.4.


Changes and fixes in Ice 3.4.1
==============================


Underscores allowed in Slice
----------------------------

Prior versions of Ice did not permit underscores to be used in Slice
identifiers. We have eliminated that restriction in Ice 3.4.1 with a
new translator option (--underscore).

Please note that there are several important issues to consider if you
plan to incorporate underscores into your Slice definitions:

* Interoperability

  Renaming an existing Slice definition always raises the possibility
  of interoperability problems with existing applications. Changing
  the name of any Slice definition whose type id is sent "over the
  wire" can easily break interoperability unless all applications are
  rebuilt and redeployed. Adding underscores to your Slice definitions
  presents an additional difficulty because the Slice compilers for
  older versions of Ice will not even be able to compile your new
  definitions.

* Name collisions

  With some effort, it is possible to write legal Slice definitions
  using underscores that generate name collisions in a language
  mapping. For example:

  // Slice
  module A
  {
      interface B_C { };
  };

  module A_B
  {
      interface C { };
  };

  The Slice compiler for PHP (slice2php) uses underscores to separate
  name scopes in the flattened mapping, therefore both of these
  interfaces generate the same PHP type named A_B_C.

  Here is another example:

  // Slice
  module A
  {
      interface B
      {
          void op();
          void begin_op();
      };

      struct Callback_B_op
      {
          string s;
      };
  };

  These Slice definitions cause collisions with generated code that
  supports asynchronous invocations.

  Although these are contrived examples written intentionally to cause
  errors, they highlight the importance of selecting your Slice
  identifiers with careful consideration of your target language
  mappings.

* Freeze

  As discussed in the Interoperability section above, renaming Slice
  types poses a range of compatibility issues. If you use Freeze to
  store instances of Slice types persistently, be aware that renaming
  Slice types usually requires that you also migrate your Freeze
  databases because Slice type names are embedded in your records (if
  you store instances of Slice classes) and also appear in the Freeze
  catalog.


Freeze locking
--------------

Ice 3.4.0 added a locking mechanism to Freeze to prevent multiple
processes from opening the same database environment simultaneously,
which can lead to data corruption. Freeze uses a lock file named
__Freeze/lock, which can be found in the database environment
directory.

In Ice 3.4.1 we added the property Freeze.DbEnv.<env>.LockFile. This
property determines whether Freeze attempts to create the lock file
for the named database environment. The default value of this property
is 1, meaning the lock file is created. Applications should not
normally need to disable the lock file, but it is useful for utility
programs such as the FreezeScript tools dumpdb and transformdb. By
disabling the lock file, these tools are able to inspect a database
environment that is currently open in another process, regardless of
whether that process created a lock file.

If you intend to use a FreezeScript tool on a database environment
that is currently open, please be aware that the property
Freeze.DbEnv.<env>.DbPrivate=0 must be defined for both the
FreezeScript tool as well as the other process that has opened the
environment, otherwise the database can be corrupted.


Miscellaneous changes
---------------------

* Ice 3.4.1 requires Berkeley DB 4.8.30. This version of Berkeley DB
  includes a fix for a minor memory leak that was present in earlier
  versions.

* The shrinking behavior of Ice thread pools changed in Ice 3.4.0 but
  was not documented. Users of both 3.4.0 and 3.4.1 should review the
  "Thread pool changes" section below for more information.


Features added with Ice 3.4.0
=============================


New API for Asynchronous Method Invocation (AMI)
------------------------------------------------

This release features a completely new AMI facility for C++, C#, Java,
and Python that allows you to structure your code with much greater
flexibility. To get a better understanding of the motivations for this
enhancement and how it can improve your own applications, we encourage
you to read the white papers available at the link below:

  http://www.zeroc.com/articles/index.html


Better scalability
------------------

The Ice run time underwent significant retooling to make use of
Windows completion ports and overlapped I/O for its networking
operations. As a result, server applications that handle many
connections should see a significant improvement in scalability.

Additional enhancements were made to improve scalability on all
platforms. For example, Ice now establishes an outgoing connection
and accepts an incoming connection in constant time, regardless of
the number of connections that have already been established.
Furthermore, the Ice thread pool now supports receiving and sending
data using multiple threads, which improves CPU usage on machines
with multiple cores.


New Dispatcher facility
-----------------------

In previous releases, the developer of a graphical Ice application
would need to take precautions to make sure that updates to the user
interface were performed in the proper thread. For example, graphical
applications typically use AMI because it does not block the calling
thread, but AMI callbacks are invoked from an Ice run time thread.
Since the callback cannot update the user interface directly from such
a thread, it is forced to schedule an update instead. Consequently,
the application code grew more complex and was prone to error if the
developer neglected the threading rules.

Ice 3.4 introduces the Dispatcher facility that lets you control the
thread in which servant methods and AMI callbacks are invoked. It is
especially useful for a graphical application, in which you can easily
install a custom dispatcher to guarantee that all of your servant and
callback invocations are made in a thread that can safely update the
user interface.

This technique is demonstrated in a sample application for each of
the language mappings: refer to the "MFC" demo in C++, the "swing"
demo in Java, and the "wpf" demo in C#.


Glacier2 utility classes
------------------------

Some effort is required to write an application that correctly manages
a Glacier2 session. To simplify this task, we have added utility
classes in C++, C#, Java and Python that manage the session for you.

For all of these language mappings, Ice includes a new subclass of
Ice::Application named Glacier2::Application that is intended to be
used by command-line applications that require a Glacier2 session. The
class takes care of establishing the session, keeping it alive, and
recovering from session failures.

In Java and C#, Ice also includes the Glacier2.SessionHelper class for
use in graphical applications. This class performs many of the same
tasks as Glacier2.Application.


Default servants
----------------

The traditional way of implementing a default servant was to install a
servant locator that returned the same servant for every request.
However, since default servants are one of the most common use cases
for servant locators, we have made them easier to use by adding new
operations to the ObjectAdapter interface. If you make use of default
servants, you can simplify your code by migrating your application to
this new API.


Alternate storage for IceGrid and IceStorm
------------------------------------------

IceStorm and the IceGrid registry now have the ability to use a SQL
database instead of Freeze for their persistent storage requirements.
This release supports SQLite on all platforms and PostgreSQL on Unix
platforms. If you would like to see support added for other SQL
servers, please contact info@zeroc.com.


Connection and endpoint information
-----------------------------------

Ice developers frequently want to obtain information about connections
and endpoints, as evidenced by the numerous inquiries on the user
forum about this issue. For example, the developer may want to be able
to discover the IP address of a remote client. This information was
available in prior releases, but not in a form that was easy to
manipulate.

Now it is possible to obtain more details about connections and
endpoints with the addition of the ConnectionInfo and EndpointInfo
class hierarchies. Using these classes, you can discover addresses,
ports, and other attributes of a connection or endpoint.

Note that it is inadvisable to use such addressing information for
authentication purposes, as IP addresses can easily be forged.


New Slice compiler and API for PHP
----------------------------------

Significant changes have been made to the PHP mapping and API. For
example, Ice for PHP now uses static translation via the new slice2php
compiler, and the language mapping is now more consistent with that
of Python and Ruby. For more information on migrating your PHP
application, please refer to the section titled "PHP changes" below.


Slice comments
--------------

This release offers several improvements that will be appreciated by
developers, especially those who use integrated development
environments (IDEs):
    
* The Slice compilers for Java, C#, and Python now preserve Slice
  comments in the generated code.

* Doc comments have been added to the native Ice APIs.

* The JAR files for Ice and Freeze include source code to allow IDEs
  such as Eclipse to browse the Ice source code and to display javadoc
  comments.

* For C# users that compile generated Slice code into an assembly, it
  is now useful to instruct Visual C# to emit documentation comments
  into an XML file for the assembly containing your compiled Slice
  definitions. This enables the IDE to display tooltips for your Slice
  APIs. Ice generates these XML files for its own assemblies so that
  you can view tooltips for the Ice APIs as well.


New Slice syntax for default values
-----------------------------------

It is now possible to specify in Slice the default values for data
members of classes, structures, and exceptions. The semantics are the
same as for Slice constants in that you can only specify default
values for a data member whose type is a primitive or enumeration.
For example:

// Slice
enum Color { red, green, blue };

struct Point
{
    int x = -1;
    int y = -1;
    Color c = blue;
};


Properties in the Windows registry
----------------------------------

Ice configuration properties can now be loaded from the Windows
registry by specifying a registry key as the value of the Ice.Config
property. Ice programs that run as Windows services are likely to make
use of this feature because it avoids the need to hard-code properties
in the application, eliminates the dependency on a configuration file,
and allows the program's configuration settings to be edited using
familiar registry tools.


New sample programs
-------------------

This release adds the following sample programs:

  - map_filesystem (C++, Java)

    Shows how to implement the filesystem application using a Freeze
    map.

  - interleaved (C++)

    Uses interleaved asynchronous invocations to achieve maximum
    throughput.

  - plugin (C++, Java, C#)

    Demonstrates how to write an Ice plug-in.

  - chat (Java, C#)

    A graphical chat client that uses Glacier2 to communicate with
    a C++ server.

  - swing (Java)
    wpf (C#)

    Graphical versions of the hello client.

  - hello (PHP)

    A Glacier2 client that demonstrates the use of registered
    communicators.


======================================================================
2. Upgrading your application from Ice 3.4.0
======================================================================

Since Ice 3.4.1 maintains binary compatibility with Ice 3.4.0, it is
not necessary for you to recompile your Slice files or your program
code, nor is it necessary to relink your application. The database
formats used by Ice services such as IceGrid and IceStorm have not
changed, therefore no database migration is required. Finally, this
release has not removed any APIs. Generally speaking, you are free to
use any combination of Ice 3.4.0 or Ice 3.4.1 applications and Ice
services.

The subsections below provide additional information about upgrading
to Ice 3.4.1, including administrative procedures for the supported
platforms.


RPMs (Linux)
============

For RPM installations, you can use the Ice 3.4.1 RPMs to upgrade an
existing installation of Ice 3.4.0.

For a Java application, no additional steps are necessary if your
CLASSPATH refers to /usr/share/java/Ice.jar, which is a symbolic link
that points to the actual version-specific JAR file.

For a Mono application, the ice-mono RPM for Ice 3.4.1 installs the
updated Ice run time assemblies into the Global Assembly Cache (GAC)
along with policy assemblies that enable backward compatibility with
Ice 3.4.0.


Windows
=======

The file names of the Ice for C++ run time DLLs do not contain the
patch number of a release. For example, the core Ice DLL uses the same
name (ice34.dll) for both Ice 3.4.0 and Ice 3.4.1. As a result, you
can simply substitute the 3.4.1 DLLs for the 3.4.0 DLLs. If you
install the 3.3.1 DLLs in a different directory, you will typically
need to adjust the PATH setting of a C++ application so that it can
locate the new libraries. This also applies to Python, Ruby, and PHP
applications because they use the Ice for C++ DLLs.

For a Java application, you can replace the existing Ice.jar file
with the one from Ice 3.4.1, or you can adjust the CLASSPATH setting
to point to the new JAR file.

For a .NET application, Ice for .NET includes policy assemblies that
supply the .NET run time with the required compatibility information.
Policy assemblies have names of the form policy.3.4.<package>.dll.
For example, the policy assembly for IceBox is policy.3.4.IceBox.dll.
One way to upgrade an existing .NET application to a new patch release
while maintaining binary compatibility is to install the policy
assemblies into the Global Assembly Cache (GAC) using one of the
following methods:

  - Open Windows Explorer and navigate to the directory
    C:\WINDOWS\assembly. Next, drag and drop (or copy and paste) the
    assemblies into the right-hand pane to install them in the GAC.

  - Use gacutil from the command line:

    > gacutil -i <policy.dll>

Another option is to modify the .config file of your application to
add bindingRedirect directives, as explained in the links below:

  http://msdn.microsoft.com/en-us/library/7wd6ex19.aspx
  http://msdn.microsoft.com/en-us/library/yx7xezcf.aspx

For example, in the .config file of an application you can modify the
configuration of the Ice assembly as follows:

  <dependentAssembly>
    <assemblyIdentity name="Ice" culture="neutral"
      publicKeyToken="cdd571ade22f2f16"/>
    <bindingRedirect oldVersion="3.4.0.0" newVersion="3.4.1.0"/>
    <codeBase version="3.4.1.0" href="...\Ice.dll"/>
  </dependentAssembly>

Note that "cdd571ade22f2f16" is the token corresponding to ZeroC's
public key for signing the assemblies in binary distributions. If you
built Ice from sources, your assemblies were signed using the
development key instead, which you can find in config/IceDevKey.snk.
The token for the development key is "1f998c50fec78381".

The advantage of installing the policy assemblies into the GAC is that
they establish binary compatibility for all Ice applications, whereas
modifying a .config file must be done for each application
individually.

On a development system, it is not necessary to remove your existing
Ice installation prior to installing Ice 3.4.1 unless you intend to
install Ice 3.4.1 in the same directory as your existing installation.
You may need to update your PATH setting and modify your Visual C++
directory configurations to reflect the installation directory for
Ice 3.4.1.


Binary Archives (Mac OS X, Solaris)
===================================

The README file included in each binary distribution archive
describes how to configure your environment so that the embedded
path names in the Ice for C++ shared libraries are resolved correctly.
For example, if you extracted the binary distribution for Ice 3.4.0
into /opt/Ice-3.4.0, the README file instructs you to create the
following symbolic link:

  /opt/Ice-3.4 -> /opt/Ice-3.4.0

To upgrade to Ice 3.4.1, you simply extract the binary distribution
archive into /opt/Ice-3.4.1 and reset the symbolic link to point to
the new installation:

  /opt/Ice-3.4 -> /opt/Ice-3.4.1

No additional steps are necessary for a Java application if its
CLASSPATH refers to the JAR file via the symbolic link:

  export CLASSPATH=/opt/Ice-3.4/lib/Ice.jar

This also applies for Python and Ruby applications:

  export PYTHONPATH=/opt/Ice-3.4/python
  export RUBYLIB=/opt/Ice-3.4/ruby


Source Distribution (Linux, Mac OS X, Solaris)
==============================================

If you compiled an Ice 3.4.0 source distribution and installed it via
"make install", the default installation directory uses a version-
specific name such as /opt/Ice-3.4.0. Consequently, you can build and
install the Ice 3.4.1 source distribution without affecting your
existing Ice 3.4.0 installation.

You may need to update your application's build settings to use the
new installation directory for location include and library files.
You may also need to update your shared library search path.

The relevant environment variables for each language mapping are
detailed below.

C++, Ruby, Python, PHP:

  export LD_LIBRARY_PATH=/opt/Ice-3.4.1/lib (32-bit Linux & 32-bit Solaris)
  export LD_LIBRARY_PATH=/opt/Ice-3.4.1/lib64 (64-bit Linux)
  export LD_LIBRARY_PATH_64=/opt/Ice-3.4.1/lib/amd64 (64-bit Solaris Intel)
  export LD_LIBRARY_PATH_64=/opt/Ice-3.4.1/lib/sparcv9 (64-bit Solaris SPARC)
  export DYLD_LIBRARY_PATH=/opt/Ice-3.4.1/lib (Mac OS X)

Python:

  export PYTHONPATH=/opt/Ice-3.4.1/python

Ruby:

  export RUBYLIB=/opt/Ice-3.4.1/ruby

Java:

  export CLASSPATH=/opt/Ice-3.4.1/lib/Ice.jar

Mono:

  export MONO_PATH=/opt/Ice-3.4.1/bin


Deprecated APIs
===============

This section discusses APIs and components that are now deprecated.
These APIs will be removed in a future Ice release, therefore we
encourage you to update your applications and eliminate the use of
these APIs as soon as possible.

The following APIs were deprecated in Ice 3.4.1:

* Ice.AsyncCallback

  The methods in this class were moved into its base class,
  Ice.Callback, therefore this class is no longer necessary.
  Applications that use the generic asynchronous callback facility
  should change their callbacks to inherit from Ice.Callback.


======================================================================
3. Upgrading your application from Ice 3.3
======================================================================


Compatibility
=============

A discussion of backward compatibility in Ice involves several
factors:

  - Source-code compatibility

    Ice maintains source-code compatibility between a patch release
    (e.g., 3.4.1) and the most recent minor release (e.g., 3.4.0),
    but does not guarantee source-code compatibility between minor
    releases (e.g., between 3.3 and 3.4).

    The subsections below describe the significant API changes in this
    release that may impact source-code compatibility. Furthermore,
    the "Removed APIs" and "Deprecated APIs" subsections summarize
    additional changes to Ice APIs that could affect your application.

  - Binary compatibility

    As for source-code compatibility, Ice maintains backward binary
    compatibility between a patch release and the most recent minor
    release, but does not guarantee binary compatibility between
    minor 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.

    * No action is necessary for a Python or Ruby script that loads
      its Slice files dynamically.

  - On-the-wire compatibility

    Ice always maintains protocol ("on the wire") compatibility with
    prior releases.

  - Database compatibility

    Upgrading to a new minor release of Ice often includes an upgrade
    to the supported version of Berkeley DB. In turn, this may require
    an application to migrate its databases, either because the format
    of Berkeley DB's database files has changed, or due to a change in
    the schema of the data stored in those databases.

    For example, if your application uses Freeze, it may be necessary
    for you to migrate your databases even if your schema has not
    changed.

    Certain Ice services also use Freeze in their implementation. If
    your application uses these services (IceGrid and IceStorm), it
    may be necessary for you to migrate their databases as well.

    Please refer to the relevant subsections below for migration
    instructions.

  - Interface compatibility

    Although Ice always maintains compatibility at the protocol level,
    changing Slice definitions can also lead to incompatibilities. As
    a result, Ice maintains interface compatibility between a patch
    release and the most recent minor release, but does not guarantee
    compatibility between minor releases.

    This issue is particularly relevant if your application uses Ice
    services such as IceGrid or IceStorm, as a change to an interface
    in one of these services may adversely affect your application.

    Interface changes in an Ice service can also impact compatibility
    with its administrative tools, which means it may not be possible
    to administer an Ice 3.4.x service using a tool from a previous
    minor release (or vice-versa).

    IceGrid
    -------

    Starting with Ice 3.2.0, IceGrid registries and nodes are
    interface-compatible. For example, you can use an IceGrid node
    from Ice 3.2 with a registry from Ice 3.4.

    IceGrid registry replication is only supported between registries
    using Ice 3.3 or later.

    An IceGrid node using Ice 3.3 or later is able to activate a
    server that uses Ice 3.2. The reverse is also true: an IceGrid
    node from Ice 3.2 is able to activate a server built with Ice 3.3
    or later, but only if the server's configuration properties do not
    rely on features added after Ice 3.2 (such as the ability to
    escape characters in property names and values).

    IceStorm
    --------

    Topic linking is supported between all IceStorm versions released
    after 3.0.0.


Java language mapping changes
=============================

The Java2 language mapping, which was deprecated in Ice 3.3, is no
longer supported. The Slice compiler and Ice API now use the Java5
language mapping exclusively, therefore upgrading to Ice 3.4 may
require modifications to your application's source code. The
subsections below discuss the language mapping features that are
affected by this change and describe how to modify your application
accordingly.


Metadata
--------

The global metadata directives "java:java2" and "java:java5" are no
longer supported and should be removed from your Slice files. The
Slice compiler now emits a warning about these directives.

Support for the portable metadata syntax has also been removed. This
syntax allowed Slice definitions to define custom type metadata that
the Slice compiler would translate to match the desired target
mapping. For example:

  // Slice
  ["java:type:{java.util.ArrayList}"] sequence<String> StringList;

The braces surrounding the custom type "java.util.ArrayList" directed
the Slice compiler to use "java.util.ArrayList<String>" in the Java5
mapping and "java.util.ArrayList" in the Java2 mapping.

All uses of the portable metadata syntax must be changed to use the
corresponding Java5 equivalent.


Dictionaries
------------

Since Slice dictionary types now use the Java5 mapping, recompiling
your Slice files and your application may cause the Java compiler to
emit "unchecked" warnings. This occurs when your code attempts to
assign an untyped collection class such as "java.util.Map" to a
generic type such as "java.util.Map<String, String>". Consider the
following example:

  // Slice
  dictionary<string, int> ValueMap;

  interface Table {
      void setValues(ValueMap m);
  };

A Java2 application might have used these Slice definitions as shown
below:

  // Java
  java.util.Map values = new java.util.HashMap();
  values.put(...);

  TablePrx proxy = ...;
  proxy.setValues(values); // Warning

The call to setValues() is an example of an unchecked conversion. We
recommend that you compile your application using the compiler option
shown below:

  javac -Xlint:unchecked ...

This option causes the compiler to generate descriptive warnings about
occurrences of unchecked conversions to help you find and correct the
offending code.


Contexts
--------

The Slice type Ice::Context is defined as follows:

  // Slice
  module Ice {
      dictionary<string, string> Context;
  };

As a dictionary, the Context type is subject to the same issues
regarding unchecked conversions described in the "Dictionaries"
section above. For example, each proxy operation maps to two
overloaded methods, one that omits the trailing Context parameter and
one that includes it:

  // Java
  interface TablePrx {
      void setValues(java.util.Map<String, Integer> m);  // No context

      void setValues(java.util.Map<String, Integer> m,
                     java.util.Map<String, String> ctx);
  }

If your proxy invocations make use of this parameter, you will need to
change your code to use the generic type shown above in order to
eliminate unchecked conversion warnings.


Enumerations
------------

The Java2 language mapping for a Slice enumeration generated a class
whose API differed in several ways from the standard Java5 enum type.
Consider the following enumeration:

  // Slice
  enum Color { red, green, blue };

The Java2 language mapping for Color is shown below:

  // Java
  public final class Color
  {
      // Integer constants
      public static final int _red = 0;
      public static final int _green = 1;
      public static final int _blue = 2;

      // Enumerators
      public static final Color red = ...;
      public static final Color green = ...;
      public static final Color blue = ...;

      // Helpers
      public static Color convert(int val);
      public static Color convert(String val);
      public int value();

      ...
  }

The first step in migrating to the Java5 mapping for enumerations is
to modify all switch statements that use an enumerator. Before Java
added native support for enumerations, the switch statement could only
use the integer value of the enumerator and therefore the Java2
mapping supplied integer constants for use in case statements. For
example, here is a switch statement that uses the Java2 mapping:

  // Java
  Color col = ...;
  switch(col.value())
  {
  case Color._red:
      ...
      break;
  case Color._green:
      ...
      break;
  case Color._blue:
      ...
      break;
  }

The Java5 mapping eliminates the integer constants because Java5
allows enumerators to be used in case statements. The resulting code
becomes much easier to read and write:

  // Java
  Color col = ...;
  switch(col)
  {
  case red:
      ...
      break;
  case green:
      ...
      break;
  case blue:
      ...
      break;
  }

The next step is to replace any uses of the value() or convert()
methods with their Java5 equivalents. The base class for all Java5
enumerations (java.lang.Enum) supplies methods with similar
functionality:

  static Color[] values()          // replaces convert(int)
  static Color valueOf(String val) // replaces convert(String)
  int ordinal()                    // replaces value()

For example, here is the Java5 code to convert an integer into its
equivalent enumerator:

  Color r = Color.values()[0]; // red

Note however that the convert(String) method in the Java2 mapping
returned null for an invalid argument, whereas the Java5 enum method
valueOf raises IllegalArgumentException instead.


Changes to the Java API for Freeze maps
=======================================

The Java API for Freeze maps has been revised to used Java5 generic
types and enhanced to provide additional functionality. This section
describes these changes in detail and explains how to migrate your
Freeze application to the API in Ice 3.4.


General changes
---------------

The Freeze API is now entirely type-safe, which means compiling your
application against Ice 3.4 is likely to generate unchecked conversion
warnings. The generated class for a Freeze map now implements the
java.util.SortedMap<K, V> interface, where K is the key type and V is
the value type. As a result, applications that relied on the untyped
SortedMap API (where all keys and values were treated as instances of
java.lang.Object) will encounter compiler warnings in Ice 3.4.

For example, an application might have iterated over the entries in a
map as follows:

// Old API
Object key = new Integer(5);
Object value = new Address(...);
myMap.put(key, value);
java.util.Iterator i = myMap.entrySet().iterator();
while (i.hasNext()) {
    java.util.Map.Entry e = (java.util.Map.Entry)i.next();
    Integer myKey = (Integer)e.getKey();
    Address myValue = (Address)e.getValue();
    ...
}

This code will continue to work, but the new API is both type-safe
and self-documenting:

// New API
int key = 5;
Address value = new Address(...);
myMap.put(key, value); // The key is autoboxed to Integer.
for (java.util.Map.Entry<Integer, Address> e : myMap.entrySet()) {
    Integer myKey = e.getKey();
    Address myValue = e.getValue();
    ...
}

Although migrating to the new API may require some effort, the
benefits are worthwhile because your code will be easier to read and
less prone to defects. You can also take advantage of the "autoboxing"
features in Java5 that automatically convert values of primitive types
(such as int) into their object equivalents (such as Integer).

Please refer to the Ice manual for complete details on the new API.


Enhancements
------------

Java6 introduced the java.util.NavigableMap interface, which extends
java.util.SortedMap to add some useful new methods. Although the
Freeze map API cannot implement java.util.NavigableMap directly
because Freeze must remain compatible with Java5, we have added the
Freeze.NavigableMap interface to provide much of the same
functionality. A generated Freeze map class implements NavigableMap,
as do the sub map views returned by map methods such as headMap.
The NavigableMap interface is described in the Ice manual, and you can
also refer to the Java6 API documentation.


Backward compatibility
----------------------

The Freeze Map API related to indices underwent some significant
changes in order to improve type safety and avoid unchecked
conversion warnings. These changes may cause compilation failures in a
Freeze application.

In the previous API, index comparator objects were supplied to the
Freeze map constructor in a map (in Java5 syntax, this comparators map
would have the type java.util.Map<String, java.util.Comparator>) in
which the index name was the key. As part of our efforts to improve
type safety, we also wanted to use the fully-specified type for each
index comparator (such as java.util.Comparator<Integer>). However,
given that each index could potentially use a different key type, it
is not possible to retain the previous API while remaining type-safe.

Consequently, the index comparators are now supplied as data members
of a static nested class of the Freeze map named IndexComparators. If
your application supplied custom comparators for indices, you will
need to revise your code to use IndexComparators instead. For example:

// Old API
java.util.Map indexComparators = new java.util.HashMap();
indexComparators.put("index", new MyComparator());
MyMap map = new MyMap(..., indexComparators);

// New API
MyMap.IndexComparators indexComparators =
    new MyMap.IndexComparators();
indexComparators.valueComparator = new MyComparator();
MyMap map = new MyMap(..., indexComparators);

We also encourage you to modify the definition of your comparator
classes to use the Java5 syntax, as shown in the example below:

// Old comparator
class IntComparator implements java.util.Comparator
{
    public int compare(Object o1, Object o2)
    {
        return ((Integer)o1).compareTo(o2);
    }
}

// New comparator
class IntComparator implements java.util.Comparator<Integer>
{
    public int compare(Integer i1, Integer i2)
    {
        return i1.compareTo(i2);
    }
}

The second API change that might cause compilation failures is the
removal of the following methods:

    java.util.SortedMap headMapForIndex(String name, Object key);
    java.util.SortedMap tailMapForIndex(String name, Object key);
    java.util.SortedMap subMapForIndex(String name, Object from,
                                       Object to);
    java.util.SortedMap mapForIndex(String name);

Again, this API cannot be retained in a type-safe fashion, therefore
slice2freezej now generates equivalent (and type-safe) methods for
each index in the Freeze map class.

Please refer to the Ice manual for complete details on the new API.


Finalizers
----------

In previous releases, Freeze for Java used finalizers to close objects
such as maps and connections that the application neglected to close.
Most of these finalizers have been removed in Ice 3.4, and the only
remaining finalizers simply log warning messages to alert you to the
fact that connections and iterators are not being closed explicitly.
Note that, given the uncertain nature of Java finalizers, it is quite
likely that the remaining finalizers will not be executed.


Freeze packaging
================

All Freeze-related classes are now stored in a separate JAR file named
Freeze.jar. As a result, you may need to update your build scripts,
deployment configuration, and run-time environment to include this
additional JAR file.


PHP changes
===========

The Ice extension for PHP has undergone many changes in this release.
The subsections below describe these changes in detail.


Static translation
------------------

In prior releases, Slice files were deployed with the application and
loaded at Web server startup by the Ice extension. Before each page
request, the extension directed the PHP interpreter to parse the code
that was generated from the Slice definitions.

In this release, Slice files must be translated using the new compiler
slice2php. This change offers several advantages:

* Applications may have more opportunities to improve performance
  through the use of opcode caching.

* It is no longer necessary to restart the Web server when you make
  changes to your Slice definitions, which is especially useful during
  development.

* Errors in your Slice files can now be discovered in your development
  environment, rather than waiting until the Web server reports a
  failure and then reviewing the server log to determine the problem.

* The development process becomes simpler because you can easily
  examine the generated code if you have questions about the API or
  language mapping rules.

* PHP scripts can now use all of the Ice local exceptions. In prior
  releases, only a subset of the local exception types were available,
  and all others were mapped to Ice_UnknownLocalException. See the
  section "Local exceptions" below for more information.

All of the Slice files for Ice and Ice services are translated during
an Ice build and available for inclusion in your application. At a
minimum, you must include the file Ice.php:

// PHP
require 'Ice.php';

Ice.php contains definitions for core Ice types and includes a minimal
set of generated files. To use an Ice service such as IceStorm,
include the appropriate generated file:

// PHP
require 'Ice.php';
require 'IceStorm/IceStorm.php';


Deployment
----------

With the transition to static code generation, you no longer need to
deploy Slice files with your application. Instead, you will need to
deploy the PHP code generated from your Slice definitions, along with
Ice.php, the generated code for the Ice core, and the generated code
for any Ice services your application might use.


Communicators
-------------

In prior releases, each PHP page request could access a single Ice
communicator via the $ICE global variable. The configuration of this
communicator was derived from the profile that the script loaded via
the Ice_loadProfile function. The communicator was created on demand
when $ICE was first used and destroyed automatically at the end of the
page request.

In this release, a PHP script must create its own communicator using
an API that is similar to other Ice language mappings:

  function Ice_initialize()
  function Ice_initialize($args)
  function Ice_initialize($initData)
  function Ice_initialize($args, $initData)

Ice_initialize creates a new communicator using the configuration
provided in the optional arguments. $args is an array of strings
representing command-line options, and $initData is an instance of
Ice_InitializationData.

An application that requires no configuration can initialize a
communicator as follows:

// PHP
$communicator = Ice_initialize();

More elaborate configuration scenarios are described in the section
"Configuration" below.

A script may optionally destroy its communicator:

// PHP
$communicator->destroy();

At the completion of a page request, Ice by default automatically
destroys any communicator that was not explicitly destroyed.


Registered communicators
------------------------

Applications may benefit from the ability to use a communicator
instance in multiple page requests. Reusing a communicator allows the
application to minimize the overhead associated with the communicator
lifecycle, including such activities as opening and closing
connections to Ice servers.

This release includes new APIs for registering a communicator in order
to prevent Ice from destroying it automatically at the completion of a
page request. For example, a session-based application can create a
communicator, establish a Glacier2 session, and register the
communicator. In subsequent page requests, the PHP session can
retrieve its communicator instance and continue using the Glacier2
session.

The Ice manual provides more information on this feature, and a new
sample program can be found in Glacier2/hello.


Configuration
-------------

Prior releases supported four INI settings in PHP's configuration
file:

  * ice.config
  * ice.options
  * ice.profiles
  * ice.slice

The ice.slice directive is no longer supported since Slice definitions
are now compiled statically. The remaining options are still supported
but their semantics are slightly different. They no longer represent
the configuration of a communicator; instead, they define property
sets that a script can retrieve and use to initialize a communicator.

The global INI directives ice.config and ice.options configure the
default property set. The ice.profiles directive can optionally
nominate a separate file that defines any number of named profiles,
each of which configures a property set.

As before, the profiles use an INI file syntax:

[Name1]
config=file1
options="--Ice.Trace.Network=2 ..."

[Name2]
config=file2
options="--Ice.Trace.Locator=1 ..."

A new directive, ice.hide_profiles, overwrites the value of the
ice.profiles directive as a security measure. This directive has
a default value of 1, meaning it is enabled by default.

A script can obtain a property set using the new function
Ice_getProperties. Called without an argument (or with an empty
string), the function returns the default property set:

// PHP
$props = Ice_getProperties();

Alternatively, you can pass the name of the desired profile:

// PHP
$props = Ice_getProperties("Name1");

The returned object is an instance of Ice_Properties, which supports
the standard Ice API.

For users migrating from an earlier release, you can replace a call to
Ice_loadProfile as follows:

// PHP - Old API
Ice_loadProfile('Name1');

// PHP - New API
$initData = new Ice_InitializationData;
$initData->properties = Ice_getProperties('Name1');
$ICE = Ice_initialize($initData);

(Note that it is not necessary to use the symbol $ICE for your
communicator. However, using this symbol may ease your migration to
this release.)

Ice_loadProfile also installed the PHP definitions corresponding to
your Slice types. In this release you will need to add 'require'
statements to include your generated code.

Finally, if you wish to manually configure a communicator, you can
create a property set using Ice_createProperties:

  function Ice_createProperties($args=null, $defaultProperties=null)

$args is an array of strings representing command-line options, and
$defaultProperties is an instance of Ice_Properties that supplies
default values for properties.

As an example, an application can configure a communicator as shown
below:

// PHP
$initData = new Ice_InitializationData;
$initData->properties = Ice_createProperties();
$initData->properties->setProperty("Ice.Trace.Network", "1");
...
$ICE = Ice_initialize($initData);


Namespaces
----------

This release includes optional support for PHP namespaces, which was
introduced in PHP 5.3. Support for PHP namespaces is disabled by
default; to enable it, you must build the Ice extension from source
code with USE_NAMESPACES=yes (see Make.rules or Make.rules.mak in
the php/config subdirectory). Note that the extension only supports
one mapping style at a time; installing a namespace-enabled version
of the extension requires all Ice applications on the target Web
server to use namespaces.

With namespace support enabled, you must modify your script to
include a different version of the core Ice types:

// PHP
require 'Ice_ns.php'; // Namespace version of Ice.php

You must also recompile your Slice files using the -n option to
generate namespace-compatible code:

% slice2php -n MySliceFile.ice

This mapping translates Slice modules into PHP namespaces instead of
using the "flattened" (underscore) naming scheme. For example,
Ice_Properties becomes \Ice\Properties in the namespace mapping.
However, applications can still refer to global Ice functions by their
traditional names (such as Ice_initialize) or by their namespace
equivalents (\Ice\initialize).


Local exceptions
----------------

As mentioned earlier, prior releases of Ice for PHP only supported a
limited subset of the standard local exceptions (refer to
Ice/LocalException.ice for the definitions of these exceptions).
An occurrence of an unsupported local exception was mapped to
Ice_UnknownLocalException.

This release adds support for all local exceptions, which allows an
application to more easily react to certain types of errors:

// PHP
try
{
    $proxy->sayHello();
}
catch(Ice_ConnectionLostException $ex)
{
    // Handle connection loss
}
catch(Ice_LocalException $ex)
{
    // Handle other errors
}

This change represents a potential backward compatibility issue:
applications that previously caught Ice_UnknownLocalException may
need to be modified to catch the intended exception instead.


Downcasting
-----------

In prior releases, to downcast a proxy you had to invoke the
ice_checkedCast or ice_uncheckedCast method on a proxy and supply
a type ID:

// PHP
$hello = $proxy->ice_checkedCast("::Demo::Hello");

This API is likely to cause run-time errors because no validation is
performed on the type ID string. For example, renaming the Hello
interface to Greeting requires that you not only change all
occurrences of Demo_Hello to Demo_Greeting, but also fix any type IDs
that your code might have embedded. The PHP interpreter does not
provide any assistance if you forget to make this change, and you will
only discover it when that particular line of code is executed and
fails.

To improve this situation, a minimal class is now generated for each
proxy type. The purpose of this class is to supply checkedCast and
uncheckedCast static methods:

class Demo_HelloPrx
{
    public static function checkedCast($proxy, $facetOrCtx=null,
                                       $ctx=null);

    public static function uncheckedCast($proxy, $facet=null);
}

Now your application can downcast a proxy as follows:

// PHP
$hello = Demo_HelloPrx::checkedCast($proxy);

You can continue to use ice_checkedCast and ice_uncheckedCast but we
recommend migrating your application to the new methods.


Other API changes
-----------------

This section describes additional changes to the Ice API in this
release:

- The global variable $ICE is no longer defined. An application must
  now initialize its own communicator as described above in the
  "Communicators" section.

- Removed the following communicator methods:

  $ICE->setProperty()
  $ICE->getProperty()

  The equivalent methods are:

  $communicator->getProperties()->setProperty()
  $communicator->getProperties()->getProperty()

- Removed the following global functions:

  Ice_stringToIdentity()
  Ice_identityToString()

  The equivalent methods are:

  $communicator->stringToIdentity()
  $communicator->identityToString()

- These functions have also been removed:

  Ice_loadProfile()
  Ice_loadProfileWithArgs()
  Ice_dumpProfile()

  Refer to the "Configuration" section above for more information.


Thread pool changes
===================

A thread pool supports the ability to automatically grow and shrink
as the demand for threads changes, within the limits set by the
thread pool's configuration. In prior releases, the rate at which a
thread pool shrinks was not configurable, but Ice 3.4.0 introduces the
ThreadIdleTime property to allow you to specify how long a thread pool
thread must remain idle before it terminates to conserve resources.

Please refer to the "Ice Threading Model" section of the Ice manual
for more information on this behavior.


IceSSL changes
==============

With the addition of the ConnectionInfo classes in this release (see
"New Features" above), the IceSSL::ConnectionInfo structure has
changed from a native type to a Slice class. This change has several
implications for existing applications:

* As a Slice class, IceSSL::ConnectionInfo cannot provide the X509
  certificate chain in its native form, therefore the chain is
  provided as a sequence of strings representing the encoded form
  of each certificate. You can use language-specific facilities to
  convert these strings back to certificate objects.

* For your convenience, we have added a native subclass of
  IceSSL::ConnectionInfo called IceSSL::NativeConnectionInfo. This
  class provides the certificate chain as certificate objects.

* The CertificateVerifier interface now uses NativeConnectionInfo
  instead of ConnectionInfo. If your application configures a
  custom certificate verifier, you will need to modify your
  implementation accordingly.

* In C++, also note that NativeConnectionInfo is now managed by a
  smart pointer, therefore the signature of the certificate verifier
  method becomes the following:

    virtual bool verify(const IceSSL::NativeConnectionInfoPtr&) = 0;

* The getConnectionInfo() helper function has been removed because its
  functionality has been replaced by the Connection::getInfo()
  operation. For example, in prior releases a C++ application would do
  the following:

    Ice::ConnectionPtr con = ...
    IceSSL::ConnectionInfo info = IceSSL::getConnectionInfo(con);

  Now the application should do this:

    Ice::ConnectionPtr con = ...
    IceSSL::ConnectionInfoPtr info =
        IceSSL::ConnectionInfoPtr::dynamicCast(con->getInfo());

  Alternatively, the application can downcast to the native class:
  
    Ice::ConnectionPtr con = ...
    IceSSL::NativeConnectionInfoPtr info =
        IceSSL::NativeConnectionInfoPtr::dynamicCast(con->getInfo());


Migrating IceStorm and IceGrid databases
========================================

No changes were made to the database schema for IceStorm or IceGrid in
this release. However, you still need to update your databases as
described in the "Migrating Freeze databases" section below.


Migrating Freeze Databases
==========================

No changes were made that would affect the content of your Freeze
databases. However, we upgraded the version of Berkeley DB, therefore
when upgrading to Ice 3.4 you must also upgrade your database to the
Berkeley DB 4.8 format. The only change that affects Freeze is
the format of Berkeley DB's log file.

The instructions below assume that the database environment to be
upgraded resides in a directory named "db" in the current working
directory. For a more detailed discussion of database migration,
please refer to the Berkeley DB Upgrade Process:

 http://www.oracle.com/technology/documentation/berkeley-db/db/ref/upgrade/process.html

To migrate your database:

 1. Shut down the old version of the application.

 2. Make a backup copy of the database environment:

    > cp -r db backup.db      (Unix)
    > xcopy /E db backup.db   (Windows)

 3. Locate the correct version of the Berkeley DB recovery tool
    (usually named db_recover). It is essential that you use the
    db_recover executable that matches the Berkeley DB version of your
    existing Ice release. For Ice 3.3, use db_recover from Berkeley DB
    4.6. You can verify the version of your db_recover tool by running
    it with the -V option:

    > db_recover -V

 4. Use the db_recover tool to run recovery on the database
    environment:

    > db_recover -h db

 5. Recompile and install the new version of the application.

 6. Force a checkpoint using the db_checkpoint utility. Note that you
    must use the db_checkpoint utility from Berkeley DB 4.8 when
    performing this step.

    > db_checkpoint -1 -h db

 7. Restart the application.


Removed APIs
============

This section describes APIs that were deprecated in a previous release
and have now been removed. Your application may no longer compile
successfully if it relies on one of these APIs.

The following APIs were removed in Ice 3.4:

* Glacier2.AddUserToAllowCategories

  Use Glacier2.Filter.Category.AcceptUser instead.

* Glacier2.AllowCategories

  Use Glacier2.Filter.Category.Accept instead.

* Ice.UseEventLog

  Ice services (applications that use the C++ class Ice::Service)
  always use the Windows event log by default.

* Communicator::setDefaultContext
* Communicator::getDefaultContext
* ObjectPrx:ice_defaultContext

  Use the communicator's implicit context instead.

* nonmutating keyword

  This keyword is no longer supported.

* Freeze.UseNonmutating

  Support for this property was removed along with the nonmutating
  keyword.

* Ice::NegativeSizeException

  The run time now throws UnmarshalOutOfBoundsException or
  MarshalException instead.

* slice2docbook

  This utility is no longer included in Ice.

* Ice::AMD_Array_Object_ice_invoke

  A new overloading of ice_response in the AMD_Object_ice_invoke class
  makes AMD_Array_Object_ice_invoke obsolete.

* Java2 mapping

  The Java2 mapping is no longer supported. Refer to "Java language
  mapping changes" for more information.


Deprecated APIs
===============

This section discusses APIs and components that are now deprecated.
These APIs will be removed in a future Ice release, therefore we
encourage you to update your applications and eliminate the use of
these APIs as soon as possible.

The following APIs were deprecated in Ice 3.4:

* Asynchronous Method Invocation (AMI) interface

  The AMI interface in Ice 3.3 and earlier is now deprecated for C++,
  Java, and C#.

* Glacier2.AddSSLContext

  Replaced by Glacier2.AddConnectionContext.

* Standard platform methods should be used instead of the following:

  Ice.Object.ice_hash()         // Use hashCode
  Ice.ObjectPrx.ice_getHash()   // Use hashCode
  Ice.ObjectPrx.ice_toString()  // Use toString

  In Java, use hashCode and toString. In C#, use GetHashCode and
  ToString. In Ruby, use hash instead of ice_getHash.

* Ice.Util.generateUUID()

  In Java use java.util.UUID.randomUUID().toString(). In C# use
  System.Guid.NewGuid.ToString().


======================================================================
4. Upgrading your application from Ice 3.2 or earlier releases
======================================================================

In addition to the information provided in the preceding section
("Upgrading your application from Ice 3.3"), users who are upgrading
from Ice 3.2 or earlier should also review the subsections below.


Migrating IceStorm databases
============================

Ice 3.4 supports the migration of IceStorm databases from Ice 3.1 and
from Ice 3.2. Migration from earlier Ice versions may work, but is not
officially supported. If you require assistance with such migration, 
please contact support@zeroc.com.

To migrate, first stop your IceStorm servers.

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

$ cp -r db recovered.db

Locate the correct version of the Berkeley DB recovery tool
(usually named db_recover). It is essential that you use the
db_recover executable that matches the Berkeley DB version of your
existing Ice release. For Ice 3.1, use db_recover from Berkeley DB
4.3.29. For Ice 3.2, use db_recover from Berkeley DB 4.5. You can
verify the version of your db_recover tool by running it with the
-V option:

$ db_recover -V

Now run the utility on your copy of the database environment:

$ db_recover -h recovered.db

Change to the location where you will store the database environments
for IceStorm 3.4:

$ 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

Upon completion, the "db" directory contains the migrated IceStorm
databases.


Migrating IceGrid databases
===========================

Ice 3.4 supports the migration of IceGrid databases from Ice 3.1 and
from Ice 3.2. Migration from earlier Ice versions may work, but is not
officially supported. If you require assistance with such migration, 
please contact support@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

Locate the correct version of the Berkeley DB recovery tool
(usually named db_recover). It is essential that you use the
db_recover executable that matches the Berkeley DB version of your
existing Ice release. For Ice 3.1, use db_recover from Berkeley DB
4.3.29. For Ice 3.2, use db_recover from Berkeley DB 4.5. You can
verify the version of your db_recover tool by running it with the
-V option:

$ db_recover -V

Now run the utility on your copy of the database environment:

$ db_recover -h recovered.db

Change to the location where you will store the database environments
for IceGrid 3.4:

$ cd <new-location>

Next, run the upgradeicegrid.py utility located in the `config'
directory of your Ice distribution (or in /usr/share/Ice-3.4.1 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

Upon completion, the "db" directory contains the migrated IceStorm
databases.

By default, the migration utility assumes that the servers deployed
with IceGrid also use Ice 3.4. 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 you are 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.


Migrating Freeze Databases
==========================

No changes were made that would affect the content of your Freeze
databases. However, we upgraded the version of Berkeley DB, therefore
when upgrading to Ice 3.4 you must also upgrade your database to the
Berkeley DB 4.8 format. The only change that affects Freeze is
the format of Berkeley DB's log file.

The instructions below assume that the database environment to be
upgraded resides in a directory named "db" in the current working
directory. For a more detailed discussion of database migration,
please refer to the Berkeley DB Upgrade Process:

 http://www.oracle.com/technology/documentation/berkeley-db/db/ref/upgrade/process.html

To migrate your database:

 1. Shut down the old version of the application.

 2. Make a backup copy of the database environment:

    > cp -r db backup.db      (Unix)
    > xcopy /E db backup.db   (Windows)

 3. Locate the correct version of the Berkeley DB recovery tool
    (usually named db_recover). It is essential that you use the
    db_recover executable that matches the Berkeley DB version of your
    existing Ice release. For Ice 3.1, use db_recover from Berkeley DB
    4.3.29. For Ice 3.2, use db_recover from Berkeley DB 4.5. You can
    verify the version of your db_recover tool by running it with the
    -V option:

    > db_recover -V

 4. Use the db_recover tool to run recovery on the database
    environment:

    > db_recover -h db

 5. Recompile and install the new version of the application.

 6. Force a checkpoint using the db_checkpoint utility. Note that you
    must use the db_checkpoint utility from Berkeley DB 4.8 when
    performing this step.

    > db_checkpoint -1 -h db

 7. Restart the application.


Removed APIs
============

This section describes APIs that were deprecated in a previous release
and have now been removed. Your application may no longer compile
successfully if it relies on one of these APIs.

The following APIs were removed in Ice 3.3:

* 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.

Please refer to "Removed APIs" in Section 2 for information on APIs
that were removed in Ice 3.4.


Deprecated APIs
===============

This section discusses APIs and components that are now deprecated.
These APIs will be removed in a future Ice release, therefore we
encourage you to update your applications and eliminate the use of
these APIs as soon as possible.

The following APIs were deprecated in Ice 3.3:

* 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.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.

Please refer to "Deprecated APIs" in Section 2 for information on APIs
that were deprecated in Ice 3.4.


======================================================================
5. Platform-specific notes
======================================================================


Supported platforms
-------------------

This release supports the operating systems, compilers, and run-time
environments listed in the link below:

  http://www.zeroc.com/platforms_3_4_0.html


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.


IBM JDK
--------

The IBM JDK ships with limited jurisdiction policy files for the
cryptographic libraries. For more information, including a link to
download unrestricted jurisdiction policy files, see:

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

Once you have downloaded the policy files, unpack them into this
directory:

  /usr/lib/jvm-private/java-1_6_0-ibm/jce/vanilla


======================================================================
6. Known Problems
======================================================================


iceca failure on SLES11
-----------------------

The Ice Certificate Authority (iceca) script may fail to import
OpenSSL-generated certificates into a Java keystore. This failure
occurs when using the following command-line options:

  iceca java --import ...

The import fails with an error similar to:

  lengthTag=127, too big

The error is caused by an incompatibility between the JDK's keytool
and the version of OpenSSL that is included with SLES11 (OpenSSL
0.9.8h). To work around this issue, you can install a newer version of
OpenSSL. Note that it is not necessary to rebuild Ice with the new
OpenSSL version; the only requirement is that you have the new
"openssl" executable in your PATH when running "iceca java --import".
