====================================================================== 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..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..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..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 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: 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 StringList; The braces surrounding the custom type "java.util.ArrayList" directed the Slice compiler to use "java.util.ArrayList" 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". Consider the following example: // Slice dictionary 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 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 m); // No context void setValues(java.util.Map m, java.util.Map 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 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 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) 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). 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 { 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 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 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 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 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 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: .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 .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 .CollocationOptimized, respectively. * .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 .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".