[asterisk-scf-commits] asterisk-scf/release/ice.git branch "upstream" created.
Commits to the Asterisk SCF project code repositories
asterisk-scf-commits at lists.digium.com
Fri Jun 17 16:24:52 CDT 2011
branch "upstream" has been created
at b56f6be2fca8b4c8b67a00171d0586ecfcb30be7 (commit)
- Log -----------------------------------------------------------------
commit b56f6be2fca8b4c8b67a00171d0586ecfcb30be7
Author: Kevin P. Fleming <kpfleming at digium.com>
Date: Fri Jun 17 16:24:17 2011 -0500
Imported Upstream Version 3.4.2
diff --git a/CHANGES b/CHANGES
index 06ac400..1203101 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,5 @@
======================================================================
-CHANGES for Ice 3.4.1
+CHANGES for Ice 3.4.2
======================================================================
The entries below contain brief descriptions of the changes in a
@@ -20,6 +20,223 @@ subdirectory of each language mapping (e.g., cpp/CHANGES).
======================================================================
+Changes since version 3.4.1
+======================================================================
+
+
+General Changes
+===============
+
+- The operation mode sent over the wire for the Object operations
+ ice_ping, ice_isA, ice_ids, and ice_id should be Nonmutating, but
+ the language mappings were inconsistent in this respect. All
+ language mappings now send the correct mode.
+
+- Fixed a bug where under certain circumstances, Ice would
+ indefinitely re-try to add a proxy to the Glacier2 routing table.
+
+- Improved queuing of Glacier2 requests to the client to not invoke
+ requests if the client connection already has requests pending for
+ send. Instead, Glacier2 waits for the pending requests to be
+ sent. This allow request overriding to occur more often when the
+ client connection is slow.
+
+- Fixed bug where an IceGrid node or registry could hang for a long
+ time on startup if some IceGrid registry replicas weren't reachable.
+
+- Added throwLocalException method to the Ice AsyncResult class. If
+ the request fails with a local exception, this method throws the
+ local exception.
+
+- Fixed a bug that caused a crash if a timeout occurs while sending
+ an AMI request and if automatic retry is enabled (the default).
+
+- It is now possible to use a constant as the default value for a data
+ member. For example:
+
+ // Slice
+ const int MIN = 1;
+
+ struct Info
+ {
+ int size = MIN;
+ };
+
+ It is also possible for a constant to refer to another constant:
+
+ // Slice
+ const int MAXIMUM_SIZE = 100;
+ const int DEFAULT_SIZE = MAXIMUM_SIZE;
+
+
+C++ Changes
+===========
+
+- Fixed a bug in the Linux epoll selector implementation that could
+ cause hangs when using the thread pool serialization mode.
+
+- Fixed a memory leak in IceSSL on Windows.
+
+- Fixed a bug in the generated code for a Slice structure containing
+ at least one data member that declares a default value. The
+ constructors were not being exported correctly in this case.
+
+- Fixed a bug where the IceUtil::Timer thread could die in case very
+ large delays were specified.
+
+- Removed extra include/IceGrid/Perf.h file.
+
+
+Java Changes
+============
+
+- Added support for Android.
+
+- Added overloaded constructors for user and system exceptions that
+ accept a Throwable argument.
+
+- Added an ice_staticId method to generated PrxHelper classes.
+
+- Fixed a bug in slice2java in which a floating point default value
+ could cause a compile error.
+
+- Fixed a bug where Ice.ServerIdleTime wouldn't consistently shutdown
+ servers after the given period of inactivity.
+
+
+C# Changes
+==========
+
+- Added support for the .NET Compact Framework.
+
+- Added demo/Ice/compact, which is a simple graphical client that uses
+ Ice for .NET Compact Framework.
+
+- Fixed bugs in the generated code that caused naming conflicts when
+ using a Slice module named 'System'.
+
+- Added an ice_staticId method to generated PrxHelper classes.
+
+- Fixed a bug in the generated code when a Slice class uses the
+ property mapping and declares default values for its members.
+
+
+Python Changes
+==============
+
+- Fixed bug where None was not recognized as a keyword.
+
+
+Ruby Changes
+============
+
+- Fixed a bug in the Ice extension that would cause an ArgumentError
+ to be raised when attempting to print a byte sequence whose value is
+ a string that contains null bytes.
+
+
+PHP Changes
+===========
+
+- Fixed a bug that caused 'undefined symbol IcePHP__t_XXX' errors when
+ Ice.php or a generated file is included from a non-global scope.
+
+- slice2php now generates 'require_once' statements corresponding to
+ Slice #include directives, replacing the 'require' statements used
+ in previous releases.
+
+- Fixed a bug in the Ice extension that caused Ice-related INI
+ settings to be ignored.
+
+
+Visual Studio Add-in Changes
+============================
+
+- Fixed a bug that prevented the Add-in from automatically compiling
+ Slice files when using a non-English version of Visual Studio.
+
+- Improved the layout and wording of the Ice Configuration dialogs.
+
+- Added $(IceHome) macro to VS 2008 project configurations.
+
+- Changed C++ project configurations to use $(IceHome) macro in
+ configuration settings.
+
+- Removed Ice Home field from "Ice Configuration" dialog. Projects
+ now always use the Ice installation corresponding to the location
+ of the add-in DLL.
+
+- Fixed issues that prevented the use of solution folders in Ice
+ projects.
+
+- Fixed an issue that caused the add-in to not work when using
+ Visual Studio 2010 and "Solution Navigator".
+
+- Added a check to prevent incorrect Runtime library usage in C++
+ projects.
+
+- Added support for .NET Smart Device project types used by the .NET
+ Compact Framework.
+
+- Improved add-in output messages.
+
+- Fixed an issue that produced a deadlock in Visual Studio when
+ Slice compiler output was large enough to fill the output buffer.
+
+- Fixed support for parallel builds. The Slice compiler was run
+ several times, once for each parallel build. Now the Slice
+ compiler is run only once, before all parallel builds begin.
+
+- Fixed an issue that could cause errors with Visual Studio if a
+ Slice file was saved while the project was building.
+
+- Fixed the add-in to work properly when --header-ext and
+ --source-ext are present in Extra Compiler Options.
+
+- Fixed the add-in to support building Freeze demos without the need
+ to set environment variables.
+
+- Fixed the add-in to always open generated files as read only;
+ previously the generated files were not opened read only until the
+ first project build.
+
+- Added support for setting the output directory for generated files,
+ making the add-in more VCS friendly.
+
+- Added support for .NET DEVPATH.
+
+- Added support for canceling changes in configuration dialogs. All
+ the configuration dialogs now have OK, Cancel, Apply buttons with
+ the standard semantics.
+
+- Added warnings to prevent incorrect options from being entered in
+ Extra Compiler Options.
+
+- Added a timestamp to Slice build output, which is only printed when
+ the trace level is Debug.
+
+- The add-in now supports command-line builds.
+
+- The add-in now avoids making extraneous changes to projects that
+ could result in merge issues when projects are in a shared
+ development.
+
+- The add-in no longer overrides the debug environment setting for
+ PATH, but rather appends appropriately.
+
+- On the loss of focus when adding an include directory in the Slice
+ Include Path, the addition is now saved rather than lost.
+
+- Fixed an issue where moving a Slice-generated file to a filter so
+ that it would be ignored by source control did not always work
+ because the generated files could be moved back into the regular
+ Source Files list by a build.
+
+- Improved the tracing output generated by the add-in and changed
+ the tracing options.
+
+
+======================================================================
Changes since version 3.4.0
======================================================================
diff --git a/ICE_LICENSE b/ICE_LICENSE
index fcf54ae..43ea757 100644
--- a/ICE_LICENSE
+++ b/ICE_LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2003-2010 ZeroC, Inc. All rights reserved.
+Copyright (c) 2003-2011 ZeroC, Inc. All rights reserved.
This copy of Ice is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
diff --git a/Makefile b/Makefile
index 0a60f1d..6ea41de 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
# **********************************************************************
#
-# Copyright (c) 2003-2010 ZeroC, Inc. All rights reserved.
+# Copyright (c) 2003-2011 ZeroC, Inc. All rights reserved.
#
# This copy of Ice is licensed to you under the terms described in the
# ICE_LICENSE file included in this distribution.
diff --git a/Makefile.mak b/Makefile.mak
index 79988f9..5e384c4 100644
--- a/Makefile.mak
+++ b/Makefile.mak
@@ -1,6 +1,6 @@
# **********************************************************************
#
-# Copyright (c) 2003-2010 ZeroC, Inc. All rights reserved.
+# Copyright (c) 2003-2011 ZeroC, Inc. All rights reserved.
#
# This copy of Ice is licensed to you under the terms described in the
# ICE_LICENSE file included in this distribution.
@@ -21,8 +21,8 @@ CLEAN_SUBDIRS = rb $(CLEAN_SUBDIRS)
DEPEND_SUBDIRS = $(DEPEND_SUBDIRS) rb
INSTALL_SUBDIRS = $(INSTALL_SUBDIRS) rb
!else
-SUBDIRS = $(SUBDIRS) cs vb vsplugin
-CLEAN_SUBDIRS = cs vb vsplugin $(CLEAN_SUBDIRS)
+SUBDIRS = $(SUBDIRS) cs vb vsaddin
+CLEAN_SUBDIRS = cs vb vsaddin $(CLEAN_SUBDIRS)
DEPEND_SUBDIRS = $(DEPEND_SUBDIRS) cs vb
INSTALL_SUBDIRS = $(INSTALL_SUBDIRS) cs
!endif
@@ -75,6 +75,6 @@ php::
@echo "making all in php" && \
cmd /c "cd php && $(MAKE) -nologo -f Makefile.mak $(MAKEFLAGS) all" || exit 1
-vsplugin::
- @echo "making all in vsplugin" && \
- cmd /c "cd vsplugin && $(MAKE) -nologo -f Makefile.mak $(MAKEFLAGS) all" || exit 1
+vsaddin::
+ @echo "making all in vsaddin" && \
+ cmd /c "cd vsaddin && $(MAKE) -nologo -f Makefile.mak $(MAKEFLAGS) all" || exit 1
diff --git a/README b/README
index cc3f228..68651cc 100644
--- a/README
+++ b/README
@@ -1,6 +1,6 @@
This archive contains the Ice source code for the C++, Java, .NET,
-Python, Ruby and PHP language mappings. The vsplugin subdirectory
-contains the source code for Ice Visual Studio Extension.
+Python, Ruby and PHP language mappings. The vsaddin subdirectory
+contains the source code for the Ice Visual Studio Add-In.
Please refer to the README and INSTALL files in the appropriate
subdirectory for specific information on each language mapping.
diff --git a/RELEASE_NOTES b/RELEASE_NOTES
index aaeca42..c4c9e00 100644
--- a/RELEASE_NOTES
+++ b/RELEASE_NOTES
@@ -1,2081 +1 @@
-======================================================================
-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 at 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 at 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
-===========================
-
... 226465 lines suppressed ...
--
asterisk-scf/release/ice.git
More information about the asterisk-scf-commits
mailing list