1
======================================================================
2
Release notes for Ice 3.4.1
3
======================================================================
8
This document outlines changes and improvements in this release that
9
may affect the operation of your applications or have an impact on
10
your source code. Refer to the "Upgrading" sections for more
11
information about migrating to a new Ice release.
13
For a detailed list of the changes in this release, please refer to
14
the CHANGES file included in your Ice distribution.
21
- Changes and fixes in Ice 3.4.1
22
- Features added with Ice 3.4.0
23
2. Upgrading your application from Ice 3.4.0
29
3. Upgrading your application from Ice 3.3
31
- Java language mapping changes
32
- Changes to the Java API for Freeze maps
37
- Migrating IceStorm and IceGrid databases
38
- Migrating Freeze databases
41
4. Upgrading your application from Ice 3.2 or earlier releases
42
- Migrating IceStorm databases
43
- Migrating IceGrid databases
44
- Migrating Freeze databases
47
5. Platform-specific notes
53
- iceca failure on SLES11
56
======================================================================
58
======================================================================
60
This section discusses the significant enhancements in Ice 3.4.
63
Changes and fixes in Ice 3.4.1
64
==============================
67
Underscores allowed in Slice
68
----------------------------
70
Prior versions of Ice did not permit underscores to be used in Slice
71
identifiers. We have eliminated that restriction in Ice 3.4.1 with a
72
new translator option (--underscore).
74
Please note that there are several important issues to consider if you
75
plan to incorporate underscores into your Slice definitions:
79
Renaming an existing Slice definition always raises the possibility
80
of interoperability problems with existing applications. Changing
81
the name of any Slice definition whose type id is sent "over the
82
wire" can easily break interoperability unless all applications are
83
rebuilt and redeployed. Adding underscores to your Slice definitions
84
presents an additional difficulty because the Slice compilers for
85
older versions of Ice will not even be able to compile your new
90
With some effort, it is possible to write legal Slice definitions
91
using underscores that generate name collisions in a language
105
The Slice compiler for PHP (slice2php) uses underscores to separate
106
name scopes in the flattened mapping, therefore both of these
107
interfaces generate the same PHP type named A_B_C.
109
Here is another example:
126
These Slice definitions cause collisions with generated code that
127
supports asynchronous invocations.
129
Although these are contrived examples written intentionally to cause
130
errors, they highlight the importance of selecting your Slice
131
identifiers with careful consideration of your target language
136
As discussed in the Interoperability section above, renaming Slice
137
types poses a range of compatibility issues. If you use Freeze to
138
store instances of Slice types persistently, be aware that renaming
139
Slice types usually requires that you also migrate your Freeze
140
databases because Slice type names are embedded in your records (if
141
you store instances of Slice classes) and also appear in the Freeze
148
Ice 3.4.0 added a locking mechanism to Freeze to prevent multiple
149
processes from opening the same database environment simultaneously,
150
which can lead to data corruption. Freeze uses a lock file named
151
__Freeze/lock, which can be found in the database environment
154
In Ice 3.4.1 we added the property Freeze.DbEnv.<env>.LockFile. This
155
property determines whether Freeze attempts to create the lock file
156
for the named database environment. The default value of this property
157
is 1, meaning the lock file is created. Applications should not
158
normally need to disable the lock file, but it is useful for utility
159
programs such as the FreezeScript tools dumpdb and transformdb. By
160
disabling the lock file, these tools are able to inspect a database
161
environment that is currently open in another process, regardless of
162
whether that process created a lock file.
164
If you intend to use a FreezeScript tool on a database environment
165
that is currently open, please be aware that the property
166
Freeze.DbEnv.<env>.DbPrivate=0 must be defined for both the
167
FreezeScript tool as well as the other process that has opened the
168
environment, otherwise the database can be corrupted.
171
Miscellaneous changes
172
---------------------
174
* Ice 3.4.1 requires Berkeley DB 4.8.30. This version of Berkeley DB
175
includes a fix for a minor memory leak that was present in earlier
178
* The shrinking behavior of Ice thread pools changed in Ice 3.4.0 but
179
was not documented. Users of both 3.4.0 and 3.4.1 should review the
180
"Thread pool changes" section below for more information.
183
Features added with Ice 3.4.0
184
=============================
187
New API for Asynchronous Method Invocation (AMI)
188
------------------------------------------------
190
This release features a completely new AMI facility for C++, C#, Java,
191
and Python that allows you to structure your code with much greater
192
flexibility. To get a better understanding of the motivations for this
193
enhancement and how it can improve your own applications, we encourage
194
you to read the white papers available at the link below:
196
http://www.zeroc.com/articles/index.html
202
The Ice run time underwent significant retooling to make use of
203
Windows completion ports and overlapped I/O for its networking
204
operations. As a result, server applications that handle many
205
connections should see a significant improvement in scalability.
207
Additional enhancements were made to improve scalability on all
208
platforms. For example, Ice now establishes an outgoing connection
209
and accepts an incoming connection in constant time, regardless of
210
the number of connections that have already been established.
211
Furthermore, the Ice thread pool now supports receiving and sending
212
data using multiple threads, which improves CPU usage on machines
216
New Dispatcher facility
217
-----------------------
219
In previous releases, the developer of a graphical Ice application
220
would need to take precautions to make sure that updates to the user
221
interface were performed in the proper thread. For example, graphical
222
applications typically use AMI because it does not block the calling
223
thread, but AMI callbacks are invoked from an Ice run time thread.
224
Since the callback cannot update the user interface directly from such
225
a thread, it is forced to schedule an update instead. Consequently,
226
the application code grew more complex and was prone to error if the
227
developer neglected the threading rules.
229
Ice 3.4 introduces the Dispatcher facility that lets you control the
230
thread in which servant methods and AMI callbacks are invoked. It is
231
especially useful for a graphical application, in which you can easily
232
install a custom dispatcher to guarantee that all of your servant and
233
callback invocations are made in a thread that can safely update the
236
This technique is demonstrated in a sample application for each of
237
the language mappings: refer to the "MFC" demo in C++, the "swing"
238
demo in Java, and the "wpf" demo in C#.
241
Glacier2 utility classes
242
------------------------
244
Some effort is required to write an application that correctly manages
245
a Glacier2 session. To simplify this task, we have added utility
246
classes in C++, C#, Java and Python that manage the session for you.
248
For all of these language mappings, Ice includes a new subclass of
249
Ice::Application named Glacier2::Application that is intended to be
250
used by command-line applications that require a Glacier2 session. The
251
class takes care of establishing the session, keeping it alive, and
252
recovering from session failures.
254
In Java and C#, Ice also includes the Glacier2.SessionHelper class for
255
use in graphical applications. This class performs many of the same
256
tasks as Glacier2.Application.
262
The traditional way of implementing a default servant was to install a
263
servant locator that returned the same servant for every request.
264
However, since default servants are one of the most common use cases
265
for servant locators, we have made them easier to use by adding new
266
operations to the ObjectAdapter interface. If you make use of default
267
servants, you can simplify your code by migrating your application to
271
Alternate storage for IceGrid and IceStorm
272
------------------------------------------
274
IceStorm and the IceGrid registry now have the ability to use a SQL
275
database instead of Freeze for their persistent storage requirements.
276
This release supports SQLite on all platforms and PostgreSQL on Unix
277
platforms. If you would like to see support added for other SQL
278
servers, please contact info@zeroc.com.
281
Connection and endpoint information
282
-----------------------------------
284
Ice developers frequently want to obtain information about connections
285
and endpoints, as evidenced by the numerous inquiries on the user
286
forum about this issue. For example, the developer may want to be able
287
to discover the IP address of a remote client. This information was
288
available in prior releases, but not in a form that was easy to
291
Now it is possible to obtain more details about connections and
292
endpoints with the addition of the ConnectionInfo and EndpointInfo
293
class hierarchies. Using these classes, you can discover addresses,
294
ports, and other attributes of a connection or endpoint.
296
Note that it is inadvisable to use such addressing information for
297
authentication purposes, as IP addresses can easily be forged.
300
New Slice compiler and API for PHP
301
----------------------------------
303
Significant changes have been made to the PHP mapping and API. For
304
example, Ice for PHP now uses static translation via the new slice2php
305
compiler, and the language mapping is now more consistent with that
306
of Python and Ruby. For more information on migrating your PHP
307
application, please refer to the section titled "PHP changes" below.
313
This release offers several improvements that will be appreciated by
314
developers, especially those who use integrated development
317
* The Slice compilers for Java, C#, and Python now preserve Slice
318
comments in the generated code.
320
* Doc comments have been added to the native Ice APIs.
322
* The JAR files for Ice and Freeze include source code to allow IDEs
323
such as Eclipse to browse the Ice source code and to display javadoc
326
* For C# users that compile generated Slice code into an assembly, it
327
is now useful to instruct Visual C# to emit documentation comments
328
into an XML file for the assembly containing your compiled Slice
329
definitions. This enables the IDE to display tooltips for your Slice
330
APIs. Ice generates these XML files for its own assemblies so that
331
you can view tooltips for the Ice APIs as well.
334
New Slice syntax for default values
335
-----------------------------------
337
It is now possible to specify in Slice the default values for data
338
members of classes, structures, and exceptions. The semantics are the
339
same as for Slice constants in that you can only specify default
340
values for a data member whose type is a primitive or enumeration.
344
enum Color { red, green, blue };
354
Properties in the Windows registry
355
----------------------------------
357
Ice configuration properties can now be loaded from the Windows
358
registry by specifying a registry key as the value of the Ice.Config
359
property. Ice programs that run as Windows services are likely to make
360
use of this feature because it avoids the need to hard-code properties
361
in the application, eliminates the dependency on a configuration file,
362
and allows the program's configuration settings to be edited using
363
familiar registry tools.
369
This release adds the following sample programs:
371
- map_filesystem (C++, Java)
373
Shows how to implement the filesystem application using a Freeze
378
Uses interleaved asynchronous invocations to achieve maximum
381
- plugin (C++, Java, C#)
383
Demonstrates how to write an Ice plug-in.
387
A graphical chat client that uses Glacier2 to communicate with
393
Graphical versions of the hello client.
397
A Glacier2 client that demonstrates the use of registered
401
======================================================================
402
2. Upgrading your application from Ice 3.4.0
403
======================================================================
405
Since Ice 3.4.1 maintains binary compatibility with Ice 3.4.0, it is
406
not necessary for you to recompile your Slice files or your program
407
code, nor is it necessary to relink your application. The database
408
formats used by Ice services such as IceGrid and IceStorm have not
409
changed, therefore no database migration is required. Finally, this
410
release has not removed any APIs. Generally speaking, you are free to
411
use any combination of Ice 3.4.0 or Ice 3.4.1 applications and Ice
414
The subsections below provide additional information about upgrading
415
to Ice 3.4.1, including administrative procedures for the supported
422
For RPM installations, you can use the Ice 3.4.1 RPMs to upgrade an
423
existing installation of Ice 3.4.0.
425
For a Java application, no additional steps are necessary if your
426
CLASSPATH refers to /usr/share/java/Ice.jar, which is a symbolic link
427
that points to the actual version-specific JAR file.
429
For a Mono application, the ice-mono RPM for Ice 3.4.1 installs the
430
updated Ice run time assemblies into the Global Assembly Cache (GAC)
431
along with policy assemblies that enable backward compatibility with
438
The file names of the Ice for C++ run time DLLs do not contain the
439
patch number of a release. For example, the core Ice DLL uses the same
440
name (ice34.dll) for both Ice 3.4.0 and Ice 3.4.1. As a result, you
441
can simply substitute the 3.4.1 DLLs for the 3.4.0 DLLs. If you
442
install the 3.3.1 DLLs in a different directory, you will typically
443
need to adjust the PATH setting of a C++ application so that it can
444
locate the new libraries. This also applies to Python, Ruby, and PHP
445
applications because they use the Ice for C++ DLLs.
447
For a Java application, you can replace the existing Ice.jar file
448
with the one from Ice 3.4.1, or you can adjust the CLASSPATH setting
449
to point to the new JAR file.
451
For a .NET application, Ice for .NET includes policy assemblies that
452
supply the .NET run time with the required compatibility information.
453
Policy assemblies have names of the form policy.3.4.<package>.dll.
454
For example, the policy assembly for IceBox is policy.3.4.IceBox.dll.
455
One way to upgrade an existing .NET application to a new patch release
456
while maintaining binary compatibility is to install the policy
457
assemblies into the Global Assembly Cache (GAC) using one of the
460
- Open Windows Explorer and navigate to the directory
461
C:\WINDOWS\assembly. Next, drag and drop (or copy and paste) the
462
assemblies into the right-hand pane to install them in the GAC.
464
- Use gacutil from the command line:
466
> gacutil -i <policy.dll>
468
Another option is to modify the .config file of your application to
469
add bindingRedirect directives, as explained in the links below:
471
http://msdn.microsoft.com/en-us/library/7wd6ex19.aspx
472
http://msdn.microsoft.com/en-us/library/yx7xezcf.aspx
474
For example, in the .config file of an application you can modify the
475
configuration of the Ice assembly as follows:
478
<assemblyIdentity name="Ice" culture="neutral"
479
publicKeyToken="cdd571ade22f2f16"/>
480
<bindingRedirect oldVersion="3.4.0.0" newVersion="3.4.1.0"/>
481
<codeBase version="3.4.1.0" href="...\Ice.dll"/>
484
Note that "cdd571ade22f2f16" is the token corresponding to ZeroC's
485
public key for signing the assemblies in binary distributions. If you
486
built Ice from sources, your assemblies were signed using the
487
development key instead, which you can find in config/IceDevKey.snk.
488
The token for the development key is "1f998c50fec78381".
490
The advantage of installing the policy assemblies into the GAC is that
491
they establish binary compatibility for all Ice applications, whereas
492
modifying a .config file must be done for each application
495
On a development system, it is not necessary to remove your existing
496
Ice installation prior to installing Ice 3.4.1 unless you intend to
497
install Ice 3.4.1 in the same directory as your existing installation.
498
You may need to update your PATH setting and modify your Visual C++
499
directory configurations to reflect the installation directory for
503
Binary Archives (Mac OS X, Solaris)
504
===================================
506
The README file included in each binary distribution archive
507
describes how to configure your environment so that the embedded
508
path names in the Ice for C++ shared libraries are resolved correctly.
509
For example, if you extracted the binary distribution for Ice 3.4.0
510
into /opt/Ice-3.4.0, the README file instructs you to create the
511
following symbolic link:
513
/opt/Ice-3.4 -> /opt/Ice-3.4.0
515
To upgrade to Ice 3.4.1, you simply extract the binary distribution
516
archive into /opt/Ice-3.4.1 and reset the symbolic link to point to
517
the new installation:
519
/opt/Ice-3.4 -> /opt/Ice-3.4.1
521
No additional steps are necessary for a Java application if its
522
CLASSPATH refers to the JAR file via the symbolic link:
524
export CLASSPATH=/opt/Ice-3.4/lib/Ice.jar
526
This also applies for Python and Ruby applications:
528
export PYTHONPATH=/opt/Ice-3.4/python
529
export RUBYLIB=/opt/Ice-3.4/ruby
532
Source Distribution (Linux, Mac OS X, Solaris)
533
==============================================
535
If you compiled an Ice 3.4.0 source distribution and installed it via
536
"make install", the default installation directory uses a version-
537
specific name such as /opt/Ice-3.4.0. Consequently, you can build and
538
install the Ice 3.4.1 source distribution without affecting your
539
existing Ice 3.4.0 installation.
541
You may need to update your application's build settings to use the
542
new installation directory for location include and library files.
543
You may also need to update your shared library search path.
545
The relevant environment variables for each language mapping are
548
C++, Ruby, Python, PHP:
550
export LD_LIBRARY_PATH=/opt/Ice-3.4.1/lib (32-bit Linux & 32-bit Solaris)
551
export LD_LIBRARY_PATH=/opt/Ice-3.4.1/lib64 (64-bit Linux)
552
export LD_LIBRARY_PATH_64=/opt/Ice-3.4.1/lib/amd64 (64-bit Solaris Intel)
553
export LD_LIBRARY_PATH_64=/opt/Ice-3.4.1/lib/sparcv9 (64-bit Solaris SPARC)
554
export DYLD_LIBRARY_PATH=/opt/Ice-3.4.1/lib (Mac OS X)
558
export PYTHONPATH=/opt/Ice-3.4.1/python
562
export RUBYLIB=/opt/Ice-3.4.1/ruby
566
export CLASSPATH=/opt/Ice-3.4.1/lib/Ice.jar
570
export MONO_PATH=/opt/Ice-3.4.1/bin
576
This section discusses APIs and components that are now deprecated.
577
These APIs will be removed in a future Ice release, therefore we
578
encourage you to update your applications and eliminate the use of
579
these APIs as soon as possible.
581
The following APIs were deprecated in Ice 3.4.1:
585
The methods in this class were moved into its base class,
586
Ice.Callback, therefore this class is no longer necessary.
587
Applications that use the generic asynchronous callback facility
588
should change their callbacks to inherit from Ice.Callback.
591
======================================================================
592
3. Upgrading your application from Ice 3.3
593
======================================================================
599
A discussion of backward compatibility in Ice involves several
602
- Source-code compatibility
604
Ice maintains source-code compatibility between a patch release
605
(e.g., 3.4.1) and the most recent minor release (e.g., 3.4.0),
606
but does not guarantee source-code compatibility between minor
607
releases (e.g., between 3.3 and 3.4).
609
The subsections below describe the significant API changes in this
610
release that may impact source-code compatibility. Furthermore,
611
the "Removed APIs" and "Deprecated APIs" subsections summarize
612
additional changes to Ice APIs that could affect your application.
614
- Binary compatibility
616
As for source-code compatibility, Ice maintains backward binary
617
compatibility between a patch release and the most recent minor
618
release, but does not guarantee binary compatibility between
621
The requirements for upgrading depend on the language mapping used
624
* For statically-typed languages (C++, Java, .NET), the
625
application must be recompiled.
627
* For scripting languages that use static translation, your Slice
628
files must be recompiled.
630
* No action is necessary for a Python or Ruby script that loads
631
its Slice files dynamically.
633
- On-the-wire compatibility
635
Ice always maintains protocol ("on the wire") compatibility with
638
- Database compatibility
640
Upgrading to a new minor release of Ice often includes an upgrade
641
to the supported version of Berkeley DB. In turn, this may require
642
an application to migrate its databases, either because the format
643
of Berkeley DB's database files has changed, or due to a change in
644
the schema of the data stored in those databases.
646
For example, if your application uses Freeze, it may be necessary
647
for you to migrate your databases even if your schema has not
650
Certain Ice services also use Freeze in their implementation. If
651
your application uses these services (IceGrid and IceStorm), it
652
may be necessary for you to migrate their databases as well.
654
Please refer to the relevant subsections below for migration
657
- Interface compatibility
659
Although Ice always maintains compatibility at the protocol level,
660
changing Slice definitions can also lead to incompatibilities. As
661
a result, Ice maintains interface compatibility between a patch
662
release and the most recent minor release, but does not guarantee
663
compatibility between minor releases.
665
This issue is particularly relevant if your application uses Ice
666
services such as IceGrid or IceStorm, as a change to an interface
667
in one of these services may adversely affect your application.
669
Interface changes in an Ice service can also impact compatibility
670
with its administrative tools, which means it may not be possible
671
to administer an Ice 3.4.x service using a tool from a previous
672
minor release (or vice-versa).
677
Starting with Ice 3.2.0, IceGrid registries and nodes are
678
interface-compatible. For example, you can use an IceGrid node
679
from Ice 3.2 with a registry from Ice 3.4.
681
IceGrid registry replication is only supported between registries
682
using Ice 3.3 or later.
684
An IceGrid node using Ice 3.3 or later is able to activate a
685
server that uses Ice 3.2. The reverse is also true: an IceGrid
686
node from Ice 3.2 is able to activate a server built with Ice 3.3
687
or later, but only if the server's configuration properties do not
688
rely on features added after Ice 3.2 (such as the ability to
689
escape characters in property names and values).
694
Topic linking is supported between all IceStorm versions released
698
Java language mapping changes
699
=============================
701
The Java2 language mapping, which was deprecated in Ice 3.3, is no
702
longer supported. The Slice compiler and Ice API now use the Java5
703
language mapping exclusively, therefore upgrading to Ice 3.4 may
704
require modifications to your application's source code. The
705
subsections below discuss the language mapping features that are
706
affected by this change and describe how to modify your application
713
The global metadata directives "java:java2" and "java:java5" are no
714
longer supported and should be removed from your Slice files. The
715
Slice compiler now emits a warning about these directives.
717
Support for the portable metadata syntax has also been removed. This
718
syntax allowed Slice definitions to define custom type metadata that
719
the Slice compiler would translate to match the desired target
720
mapping. For example:
723
["java:type:{java.util.ArrayList}"] sequence<String> StringList;
725
The braces surrounding the custom type "java.util.ArrayList" directed
726
the Slice compiler to use "java.util.ArrayList<String>" in the Java5
727
mapping and "java.util.ArrayList" in the Java2 mapping.
729
All uses of the portable metadata syntax must be changed to use the
730
corresponding Java5 equivalent.
736
Since Slice dictionary types now use the Java5 mapping, recompiling
737
your Slice files and your application may cause the Java compiler to
738
emit "unchecked" warnings. This occurs when your code attempts to
739
assign an untyped collection class such as "java.util.Map" to a
740
generic type such as "java.util.Map<String, String>". Consider the
744
dictionary<string, int> ValueMap;
747
void setValues(ValueMap m);
750
A Java2 application might have used these Slice definitions as shown
754
java.util.Map values = new java.util.HashMap();
757
TablePrx proxy = ...;
758
proxy.setValues(values); // Warning
760
The call to setValues() is an example of an unchecked conversion. We
761
recommend that you compile your application using the compiler option
764
javac -Xlint:unchecked ...
766
This option causes the compiler to generate descriptive warnings about
767
occurrences of unchecked conversions to help you find and correct the
774
The Slice type Ice::Context is defined as follows:
778
dictionary<string, string> Context;
781
As a dictionary, the Context type is subject to the same issues
782
regarding unchecked conversions described in the "Dictionaries"
783
section above. For example, each proxy operation maps to two
784
overloaded methods, one that omits the trailing Context parameter and
785
one that includes it:
789
void setValues(java.util.Map<String, Integer> m); // No context
791
void setValues(java.util.Map<String, Integer> m,
792
java.util.Map<String, String> ctx);
795
If your proxy invocations make use of this parameter, you will need to
796
change your code to use the generic type shown above in order to
797
eliminate unchecked conversion warnings.
803
The Java2 language mapping for a Slice enumeration generated a class
804
whose API differed in several ways from the standard Java5 enum type.
805
Consider the following enumeration:
808
enum Color { red, green, blue };
810
The Java2 language mapping for Color is shown below:
813
public final class Color
816
public static final int _red = 0;
817
public static final int _green = 1;
818
public static final int _blue = 2;
821
public static final Color red = ...;
822
public static final Color green = ...;
823
public static final Color blue = ...;
826
public static Color convert(int val);
827
public static Color convert(String val);
833
The first step in migrating to the Java5 mapping for enumerations is
834
to modify all switch statements that use an enumerator. Before Java
835
added native support for enumerations, the switch statement could only
836
use the integer value of the enumerator and therefore the Java2
837
mapping supplied integer constants for use in case statements. For
838
example, here is a switch statement that uses the Java2 mapping:
855
The Java5 mapping eliminates the integer constants because Java5
856
allows enumerators to be used in case statements. The resulting code
857
becomes much easier to read and write:
874
The next step is to replace any uses of the value() or convert()
875
methods with their Java5 equivalents. The base class for all Java5
876
enumerations (java.lang.Enum) supplies methods with similar
879
static Color[] values() // replaces convert(int)
880
static Color valueOf(String val) // replaces convert(String)
881
int ordinal() // replaces value()
883
For example, here is the Java5 code to convert an integer into its
884
equivalent enumerator:
886
Color r = Color.values()[0]; // red
888
Note however that the convert(String) method in the Java2 mapping
889
returned null for an invalid argument, whereas the Java5 enum method
890
valueOf raises IllegalArgumentException instead.
893
Changes to the Java API for Freeze maps
894
=======================================
896
The Java API for Freeze maps has been revised to used Java5 generic
897
types and enhanced to provide additional functionality. This section
898
describes these changes in detail and explains how to migrate your
899
Freeze application to the API in Ice 3.4.
905
The Freeze API is now entirely type-safe, which means compiling your
906
application against Ice 3.4 is likely to generate unchecked conversion
907
warnings. The generated class for a Freeze map now implements the
908
java.util.SortedMap<K, V> interface, where K is the key type and V is
909
the value type. As a result, applications that relied on the untyped
910
SortedMap API (where all keys and values were treated as instances of
911
java.lang.Object) will encounter compiler warnings in Ice 3.4.
913
For example, an application might have iterated over the entries in a
917
Object key = new Integer(5);
918
Object value = new Address(...);
919
myMap.put(key, value);
920
java.util.Iterator i = myMap.entrySet().iterator();
921
while (i.hasNext()) {
922
java.util.Map.Entry e = (java.util.Map.Entry)i.next();
923
Integer myKey = (Integer)e.getKey();
924
Address myValue = (Address)e.getValue();
928
This code will continue to work, but the new API is both type-safe
929
and self-documenting:
933
Address value = new Address(...);
934
myMap.put(key, value); // The key is autoboxed to Integer.
935
for (java.util.Map.Entry<Integer, Address> e : myMap.entrySet()) {
936
Integer myKey = e.getKey();
937
Address myValue = e.getValue();
941
Although migrating to the new API may require some effort, the
942
benefits are worthwhile because your code will be easier to read and
943
less prone to defects. You can also take advantage of the "autoboxing"
944
features in Java5 that automatically convert values of primitive types
945
(such as int) into their object equivalents (such as Integer).
947
Please refer to the Ice manual for complete details on the new API.
953
Java6 introduced the java.util.NavigableMap interface, which extends
954
java.util.SortedMap to add some useful new methods. Although the
955
Freeze map API cannot implement java.util.NavigableMap directly
956
because Freeze must remain compatible with Java5, we have added the
957
Freeze.NavigableMap interface to provide much of the same
958
functionality. A generated Freeze map class implements NavigableMap,
959
as do the sub map views returned by map methods such as headMap.
960
The NavigableMap interface is described in the Ice manual, and you can
961
also refer to the Java6 API documentation.
964
Backward compatibility
965
----------------------
967
The Freeze Map API related to indices underwent some significant
968
changes in order to improve type safety and avoid unchecked
969
conversion warnings. These changes may cause compilation failures in a
972
In the previous API, index comparator objects were supplied to the
973
Freeze map constructor in a map (in Java5 syntax, this comparators map
974
would have the type java.util.Map<String, java.util.Comparator>) in
975
which the index name was the key. As part of our efforts to improve
976
type safety, we also wanted to use the fully-specified type for each
977
index comparator (such as java.util.Comparator<Integer>). However,
978
given that each index could potentially use a different key type, it
979
is not possible to retain the previous API while remaining type-safe.
981
Consequently, the index comparators are now supplied as data members
982
of a static nested class of the Freeze map named IndexComparators. If
983
your application supplied custom comparators for indices, you will
984
need to revise your code to use IndexComparators instead. For example:
987
java.util.Map indexComparators = new java.util.HashMap();
988
indexComparators.put("index", new MyComparator());
989
MyMap map = new MyMap(..., indexComparators);
992
MyMap.IndexComparators indexComparators =
993
new MyMap.IndexComparators();
994
indexComparators.valueComparator = new MyComparator();
995
MyMap map = new MyMap(..., indexComparators);
997
We also encourage you to modify the definition of your comparator
998
classes to use the Java5 syntax, as shown in the example below:
1001
class IntComparator implements java.util.Comparator
1003
public int compare(Object o1, Object o2)
1005
return ((Integer)o1).compareTo(o2);
1010
class IntComparator implements java.util.Comparator<Integer>
1012
public int compare(Integer i1, Integer i2)
1014
return i1.compareTo(i2);
1018
The second API change that might cause compilation failures is the
1019
removal of the following methods:
1021
java.util.SortedMap headMapForIndex(String name, Object key);
1022
java.util.SortedMap tailMapForIndex(String name, Object key);
1023
java.util.SortedMap subMapForIndex(String name, Object from,
1025
java.util.SortedMap mapForIndex(String name);
1027
Again, this API cannot be retained in a type-safe fashion, therefore
1028
slice2freezej now generates equivalent (and type-safe) methods for
1029
each index in the Freeze map class.
1031
Please refer to the Ice manual for complete details on the new API.
1037
In previous releases, Freeze for Java used finalizers to close objects
1038
such as maps and connections that the application neglected to close.
1039
Most of these finalizers have been removed in Ice 3.4, and the only
1040
remaining finalizers simply log warning messages to alert you to the
1041
fact that connections and iterators are not being closed explicitly.
1042
Note that, given the uncertain nature of Java finalizers, it is quite
1043
likely that the remaining finalizers will not be executed.
1049
All Freeze-related classes are now stored in a separate JAR file named
1050
Freeze.jar. As a result, you may need to update your build scripts,
1051
deployment configuration, and run-time environment to include this
1052
additional JAR file.
1058
The Ice extension for PHP has undergone many changes in this release.
1059
The subsections below describe these changes in detail.
1065
In prior releases, Slice files were deployed with the application and
1066
loaded at Web server startup by the Ice extension. Before each page
1067
request, the extension directed the PHP interpreter to parse the code
1068
that was generated from the Slice definitions.
1070
In this release, Slice files must be translated using the new compiler
1071
slice2php. This change offers several advantages:
1073
* Applications may have more opportunities to improve performance
1074
through the use of opcode caching.
1076
* It is no longer necessary to restart the Web server when you make
1077
changes to your Slice definitions, which is especially useful during
1080
* Errors in your Slice files can now be discovered in your development
1081
environment, rather than waiting until the Web server reports a
1082
failure and then reviewing the server log to determine the problem.
1084
* The development process becomes simpler because you can easily
1085
examine the generated code if you have questions about the API or
1086
language mapping rules.
1088
* PHP scripts can now use all of the Ice local exceptions. In prior
1089
releases, only a subset of the local exception types were available,
1090
and all others were mapped to Ice_UnknownLocalException. See the
1091
section "Local exceptions" below for more information.
1093
All of the Slice files for Ice and Ice services are translated during
1094
an Ice build and available for inclusion in your application. At a
1095
minimum, you must include the file Ice.php:
1100
Ice.php contains definitions for core Ice types and includes a minimal
1101
set of generated files. To use an Ice service such as IceStorm,
1102
include the appropriate generated file:
1106
require 'IceStorm/IceStorm.php';
1112
With the transition to static code generation, you no longer need to
1113
deploy Slice files with your application. Instead, you will need to
1114
deploy the PHP code generated from your Slice definitions, along with
1115
Ice.php, the generated code for the Ice core, and the generated code
1116
for any Ice services your application might use.
1122
In prior releases, each PHP page request could access a single Ice
1123
communicator via the $ICE global variable. The configuration of this
1124
communicator was derived from the profile that the script loaded via
1125
the Ice_loadProfile function. The communicator was created on demand
1126
when $ICE was first used and destroyed automatically at the end of the
1129
In this release, a PHP script must create its own communicator using
1130
an API that is similar to other Ice language mappings:
1132
function Ice_initialize()
1133
function Ice_initialize($args)
1134
function Ice_initialize($initData)
1135
function Ice_initialize($args, $initData)
1137
Ice_initialize creates a new communicator using the configuration
1138
provided in the optional arguments. $args is an array of strings
1139
representing command-line options, and $initData is an instance of
1140
Ice_InitializationData.
1142
An application that requires no configuration can initialize a
1143
communicator as follows:
1146
$communicator = Ice_initialize();
1148
More elaborate configuration scenarios are described in the section
1149
"Configuration" below.
1151
A script may optionally destroy its communicator:
1154
$communicator->destroy();
1156
At the completion of a page request, Ice by default automatically
1157
destroys any communicator that was not explicitly destroyed.
1160
Registered communicators
1161
------------------------
1163
Applications may benefit from the ability to use a communicator
1164
instance in multiple page requests. Reusing a communicator allows the
1165
application to minimize the overhead associated with the communicator
1166
lifecycle, including such activities as opening and closing
1167
connections to Ice servers.
1169
This release includes new APIs for registering a communicator in order
1170
to prevent Ice from destroying it automatically at the completion of a
1171
page request. For example, a session-based application can create a
1172
communicator, establish a Glacier2 session, and register the
1173
communicator. In subsequent page requests, the PHP session can
1174
retrieve its communicator instance and continue using the Glacier2
1177
The Ice manual provides more information on this feature, and a new
1178
sample program can be found in Glacier2/hello.
1184
Prior releases supported four INI settings in PHP's configuration
1192
The ice.slice directive is no longer supported since Slice definitions
1193
are now compiled statically. The remaining options are still supported
1194
but their semantics are slightly different. They no longer represent
1195
the configuration of a communicator; instead, they define property
1196
sets that a script can retrieve and use to initialize a communicator.
1198
The global INI directives ice.config and ice.options configure the
1199
default property set. The ice.profiles directive can optionally
1200
nominate a separate file that defines any number of named profiles,
1201
each of which configures a property set.
1203
As before, the profiles use an INI file syntax:
1207
options="--Ice.Trace.Network=2 ..."
1211
options="--Ice.Trace.Locator=1 ..."
1213
A new directive, ice.hide_profiles, overwrites the value of the
1214
ice.profiles directive as a security measure. This directive has
1215
a default value of 1, meaning it is enabled by default.
1217
A script can obtain a property set using the new function
1218
Ice_getProperties. Called without an argument (or with an empty
1219
string), the function returns the default property set:
1222
$props = Ice_getProperties();
1224
Alternatively, you can pass the name of the desired profile:
1227
$props = Ice_getProperties("Name1");
1229
The returned object is an instance of Ice_Properties, which supports
1230
the standard Ice API.
1232
For users migrating from an earlier release, you can replace a call to
1233
Ice_loadProfile as follows:
1236
Ice_loadProfile('Name1');
1239
$initData = new Ice_InitializationData;
1240
$initData->properties = Ice_getProperties('Name1');
1241
$ICE = Ice_initialize($initData);
1243
(Note that it is not necessary to use the symbol $ICE for your
1244
communicator. However, using this symbol may ease your migration to
1247
Ice_loadProfile also installed the PHP definitions corresponding to
1248
your Slice types. In this release you will need to add 'require'
1249
statements to include your generated code.
1251
Finally, if you wish to manually configure a communicator, you can
1252
create a property set using Ice_createProperties:
1254
function Ice_createProperties($args=null, $defaultProperties=null)
1256
$args is an array of strings representing command-line options, and
1257
$defaultProperties is an instance of Ice_Properties that supplies
1258
default values for properties.
1260
As an example, an application can configure a communicator as shown
1264
$initData = new Ice_InitializationData;
1265
$initData->properties = Ice_createProperties();
1266
$initData->properties->setProperty("Ice.Trace.Network", "1");
1268
$ICE = Ice_initialize($initData);
1274
This release includes optional support for PHP namespaces, which was
1275
introduced in PHP 5.3. Support for PHP namespaces is disabled by
1276
default; to enable it, you must build the Ice extension from source
1277
code with USE_NAMESPACES=yes (see Make.rules or Make.rules.mak in
1278
the php/config subdirectory). Note that the extension only supports
1279
one mapping style at a time; installing a namespace-enabled version
1280
of the extension requires all Ice applications on the target Web
1281
server to use namespaces.
1283
With namespace support enabled, you must modify your script to
1284
include a different version of the core Ice types:
1287
require 'Ice_ns.php'; // Namespace version of Ice.php
1289
You must also recompile your Slice files using the -n option to
1290
generate namespace-compatible code:
1292
% slice2php -n MySliceFile.ice
1294
This mapping translates Slice modules into PHP namespaces instead of
1295
using the "flattened" (underscore) naming scheme. For example,
1296
Ice_Properties becomes \Ice\Properties in the namespace mapping.
1297
However, applications can still refer to global Ice functions by their
1298
traditional names (such as Ice_initialize) or by their namespace
1299
equivalents (\Ice\initialize).
1305
As mentioned earlier, prior releases of Ice for PHP only supported a
1306
limited subset of the standard local exceptions (refer to
1307
Ice/LocalException.ice for the definitions of these exceptions).
1308
An occurrence of an unsupported local exception was mapped to
1309
Ice_UnknownLocalException.
1311
This release adds support for all local exceptions, which allows an
1312
application to more easily react to certain types of errors:
1319
catch(Ice_ConnectionLostException $ex)
1321
// Handle connection loss
1323
catch(Ice_LocalException $ex)
1325
// Handle other errors
1328
This change represents a potential backward compatibility issue:
1329
applications that previously caught Ice_UnknownLocalException may
1330
need to be modified to catch the intended exception instead.
1336
In prior releases, to downcast a proxy you had to invoke the
1337
ice_checkedCast or ice_uncheckedCast method on a proxy and supply
1341
$hello = $proxy->ice_checkedCast("::Demo::Hello");
1343
This API is likely to cause run-time errors because no validation is
1344
performed on the type ID string. For example, renaming the Hello
1345
interface to Greeting requires that you not only change all
1346
occurrences of Demo_Hello to Demo_Greeting, but also fix any type IDs
1347
that your code might have embedded. The PHP interpreter does not
1348
provide any assistance if you forget to make this change, and you will
1349
only discover it when that particular line of code is executed and
1352
To improve this situation, a minimal class is now generated for each
1353
proxy type. The purpose of this class is to supply checkedCast and
1354
uncheckedCast static methods:
1358
public static function checkedCast($proxy, $facetOrCtx=null,
1361
public static function uncheckedCast($proxy, $facet=null);
1364
Now your application can downcast a proxy as follows:
1367
$hello = Demo_HelloPrx::checkedCast($proxy);
1369
You can continue to use ice_checkedCast and ice_uncheckedCast but we
1370
recommend migrating your application to the new methods.
1376
This section describes additional changes to the Ice API in this
1379
- The global variable $ICE is no longer defined. An application must
1380
now initialize its own communicator as described above in the
1381
"Communicators" section.
1383
- Removed the following communicator methods:
1388
The equivalent methods are:
1390
$communicator->getProperties()->setProperty()
1391
$communicator->getProperties()->getProperty()
1393
- Removed the following global functions:
1395
Ice_stringToIdentity()
1396
Ice_identityToString()
1398
The equivalent methods are:
1400
$communicator->stringToIdentity()
1401
$communicator->identityToString()
1403
- These functions have also been removed:
1406
Ice_loadProfileWithArgs()
1409
Refer to the "Configuration" section above for more information.
1415
A thread pool supports the ability to automatically grow and shrink
1416
as the demand for threads changes, within the limits set by the
1417
thread pool's configuration. In prior releases, the rate at which a
1418
thread pool shrinks was not configurable, but Ice 3.4.0 introduces the
1419
ThreadIdleTime property to allow you to specify how long a thread pool
1420
thread must remain idle before it terminates to conserve resources.
1422
Please refer to the "Ice Threading Model" section of the Ice manual
1423
for more information on this behavior.
1429
With the addition of the ConnectionInfo classes in this release (see
1430
"New Features" above), the IceSSL::ConnectionInfo structure has
1431
changed from a native type to a Slice class. This change has several
1432
implications for existing applications:
1434
* As a Slice class, IceSSL::ConnectionInfo cannot provide the X509
1435
certificate chain in its native form, therefore the chain is
1436
provided as a sequence of strings representing the encoded form
1437
of each certificate. You can use language-specific facilities to
1438
convert these strings back to certificate objects.
1440
* For your convenience, we have added a native subclass of
1441
IceSSL::ConnectionInfo called IceSSL::NativeConnectionInfo. This
1442
class provides the certificate chain as certificate objects.
1444
* The CertificateVerifier interface now uses NativeConnectionInfo
1445
instead of ConnectionInfo. If your application configures a
1446
custom certificate verifier, you will need to modify your
1447
implementation accordingly.
1449
* In C++, also note that NativeConnectionInfo is now managed by a
1450
smart pointer, therefore the signature of the certificate verifier
1451
method becomes the following:
1453
virtual bool verify(const IceSSL::NativeConnectionInfoPtr&) = 0;
1455
* The getConnectionInfo() helper function has been removed because its
1456
functionality has been replaced by the Connection::getInfo()
1457
operation. For example, in prior releases a C++ application would do
1460
Ice::ConnectionPtr con = ...
1461
IceSSL::ConnectionInfo info = IceSSL::getConnectionInfo(con);
1463
Now the application should do this:
1465
Ice::ConnectionPtr con = ...
1466
IceSSL::ConnectionInfoPtr info =
1467
IceSSL::ConnectionInfoPtr::dynamicCast(con->getInfo());
1469
Alternatively, the application can downcast to the native class:
1471
Ice::ConnectionPtr con = ...
1472
IceSSL::NativeConnectionInfoPtr info =
1473
IceSSL::NativeConnectionInfoPtr::dynamicCast(con->getInfo());
1476
Migrating IceStorm and IceGrid databases
1477
========================================
1479
No changes were made to the database schema for IceStorm or IceGrid in
1480
this release. However, you still need to update your databases as
1481
described in the "Migrating Freeze databases" section below.
1484
Migrating Freeze Databases
1485
==========================
1487
No changes were made that would affect the content of your Freeze
1488
databases. However, we upgraded the version of Berkeley DB, therefore
1489
when upgrading to Ice 3.4 you must also upgrade your database to the
1490
Berkeley DB 4.8 format. The only change that affects Freeze is
1491
the format of Berkeley DB's log file.
1493
The instructions below assume that the database environment to be
1494
upgraded resides in a directory named "db" in the current working
1495
directory. For a more detailed discussion of database migration,
1496
please refer to the Berkeley DB Upgrade Process:
1498
http://www.oracle.com/technology/documentation/berkeley-db/db/ref/upgrade/process.html
1500
To migrate your database:
1502
1. Shut down the old version of the application.
1504
2. Make a backup copy of the database environment:
1506
> cp -r db backup.db (Unix)
1507
> xcopy /E db backup.db (Windows)
1509
3. Locate the correct version of the Berkeley DB recovery tool
1510
(usually named db_recover). It is essential that you use the
1511
db_recover executable that matches the Berkeley DB version of your
1512
existing Ice release. For Ice 3.3, use db_recover from Berkeley DB
1513
4.6. You can verify the version of your db_recover tool by running
1514
it with the -V option:
1518
4. Use the db_recover tool to run recovery on the database
1523
5. Recompile and install the new version of the application.
1525
6. Force a checkpoint using the db_checkpoint utility. Note that you
1526
must use the db_checkpoint utility from Berkeley DB 4.8 when
1527
performing this step.
1529
> db_checkpoint -1 -h db
1531
7. Restart the application.
1537
This section describes APIs that were deprecated in a previous release
1538
and have now been removed. Your application may no longer compile
1539
successfully if it relies on one of these APIs.
1541
The following APIs were removed in Ice 3.4:
1543
* Glacier2.AddUserToAllowCategories
1545
Use Glacier2.Filter.Category.AcceptUser instead.
1547
* Glacier2.AllowCategories
1549
Use Glacier2.Filter.Category.Accept instead.
1553
Ice services (applications that use the C++ class Ice::Service)
1554
always use the Windows event log by default.
1556
* Communicator::setDefaultContext
1557
* Communicator::getDefaultContext
1558
* ObjectPrx:ice_defaultContext
1560
Use the communicator's implicit context instead.
1562
* nonmutating keyword
1564
This keyword is no longer supported.
1566
* Freeze.UseNonmutating
1568
Support for this property was removed along with the nonmutating
1571
* Ice::NegativeSizeException
1573
The run time now throws UnmarshalOutOfBoundsException or
1574
MarshalException instead.
1578
This utility is no longer included in Ice.
1580
* Ice::AMD_Array_Object_ice_invoke
1582
A new overloading of ice_response in the AMD_Object_ice_invoke class
1583
makes AMD_Array_Object_ice_invoke obsolete.
1587
The Java2 mapping is no longer supported. Refer to "Java language
1588
mapping changes" for more information.
1594
This section discusses APIs and components that are now deprecated.
1595
These APIs will be removed in a future Ice release, therefore we
1596
encourage you to update your applications and eliminate the use of
1597
these APIs as soon as possible.
1599
The following APIs were deprecated in Ice 3.4:
1601
* Asynchronous Method Invocation (AMI) interface
1603
The AMI interface in Ice 3.3 and earlier is now deprecated for C++,
1606
* Glacier2.AddSSLContext
1608
Replaced by Glacier2.AddConnectionContext.
1610
* Standard platform methods should be used instead of the following:
1612
Ice.Object.ice_hash() // Use hashCode
1613
Ice.ObjectPrx.ice_getHash() // Use hashCode
1614
Ice.ObjectPrx.ice_toString() // Use toString
1616
In Java, use hashCode and toString. In C#, use GetHashCode and
1617
ToString. In Ruby, use hash instead of ice_getHash.
1619
* Ice.Util.generateUUID()
1621
In Java use java.util.UUID.randomUUID().toString(). In C# use
1622
System.Guid.NewGuid.ToString().
1625
======================================================================
1626
4. Upgrading your application from Ice 3.2 or earlier releases
1627
======================================================================
1629
In addition to the information provided in the preceding section
1630
("Upgrading your application from Ice 3.3"), users who are upgrading
1631
from Ice 3.2 or earlier should also review the subsections below.
1634
Migrating IceStorm databases
1635
============================
1637
Ice 3.4 supports the migration of IceStorm databases from Ice 3.1 and
1638
from Ice 3.2. Migration from earlier Ice versions may work, but is not
1639
officially supported. If you require assistance with such migration,
1640
please contact support@zeroc.com.
1642
To migrate, first stop your IceStorm servers.
1644
Next, copy the IceStorm database environment to a second location:
1646
$ cp -r db recovered.db
1648
Locate the correct version of the Berkeley DB recovery tool
1649
(usually named db_recover). It is essential that you use the
1650
db_recover executable that matches the Berkeley DB version of your
1651
existing Ice release. For Ice 3.1, use db_recover from Berkeley DB
1652
4.3.29. For Ice 3.2, use db_recover from Berkeley DB 4.5. You can
1653
verify the version of your db_recover tool by running it with the
1658
Now run the utility on your copy of the database environment:
1660
$ db_recover -h recovered.db
1662
Change to the location where you will store the database environments
1667
Next, run the icestormmigrate utility. The first argument is the path
1668
to the old database environment. The second argument is the path to
1669
the new database environment.
1671
In this example we'll create a new directory "db" in which to store
1672
the migrated database environment:
1675
$ icestormmigrate <path-to-recovered.db> db
1677
Upon completion, the "db" directory contains the migrated IceStorm
1681
Migrating IceGrid databases
1682
===========================
1684
Ice 3.4 supports the migration of IceGrid databases from Ice 3.1 and
1685
from Ice 3.2. Migration from earlier Ice versions may work, but is not
1686
officially supported. If you require assistance with such migration,
1687
please contact support@zeroc.com.
1689
To migrate, first stop the IceGrid registry you wish to upgrade.
1691
Next, copy the IceGrid database environment to a second location:
1693
$ cp -r db recovered.db
1695
Locate the correct version of the Berkeley DB recovery tool
1696
(usually named db_recover). It is essential that you use the
1697
db_recover executable that matches the Berkeley DB version of your
1698
existing Ice release. For Ice 3.1, use db_recover from Berkeley DB
1699
4.3.29. For Ice 3.2, use db_recover from Berkeley DB 4.5. You can
1700
verify the version of your db_recover tool by running it with the
1705
Now run the utility on your copy of the database environment:
1707
$ db_recover -h recovered.db
1709
Change to the location where you will store the database environments
1714
Next, run the upgradeicegrid.py utility located in the `config'
1715
directory of your Ice distribution (or in /usr/share/Ice-3.4.1 if
1716
using an RPM installation). The first argument is the path to the old
1717
database environment. The second argument is the path to the new
1718
database environment.
1720
In this example we'll create a new directory "db" in which to store
1721
the migrated database environment:
1724
$ upgradeicegrid.py <path-to-recovered.db> db
1726
Upon completion, the "db" directory contains the migrated IceStorm
1729
By default, the migration utility assumes that the servers deployed
1730
with IceGrid also use Ice 3.4. If your servers still use an older Ice
1731
version, you need to specify the --server-version command-line option
1732
when running upgradeicegrid.py:
1734
$ upgradeicegrid.py --server-version 3.2.1 <path-to-recovered.db> db
1736
The migration utility will set the server descriptor `ice-version'
1737
attribute to the specified version and the IceGrid registry will
1738
generate configuration files compatible with the given version.
1740
If you are upgrading the master IceGrid registry in a replicated
1741
environment and the slaves are still running, you should first restart
1742
the master registry in read-only mode using the --readonly option, for
1745
$ icegridregistry --Ice.Config=config.master --readonly
1747
Next, you can connect to the master registry with icegridadmin or the
1748
IceGrid administrative GUI to ensure that the database is correct. If
1749
everything looks fine, you can shutdown and restart the master
1750
registry without the --readonly option.
1753
Migrating Freeze Databases
1754
==========================
1756
No changes were made that would affect the content of your Freeze
1757
databases. However, we upgraded the version of Berkeley DB, therefore
1758
when upgrading to Ice 3.4 you must also upgrade your database to the
1759
Berkeley DB 4.8 format. The only change that affects Freeze is
1760
the format of Berkeley DB's log file.
1762
The instructions below assume that the database environment to be
1763
upgraded resides in a directory named "db" in the current working
1764
directory. For a more detailed discussion of database migration,
1765
please refer to the Berkeley DB Upgrade Process:
1767
http://www.oracle.com/technology/documentation/berkeley-db/db/ref/upgrade/process.html
1769
To migrate your database:
1771
1. Shut down the old version of the application.
1773
2. Make a backup copy of the database environment:
1775
> cp -r db backup.db (Unix)
1776
> xcopy /E db backup.db (Windows)
1778
3. Locate the correct version of the Berkeley DB recovery tool
1779
(usually named db_recover). It is essential that you use the
1780
db_recover executable that matches the Berkeley DB version of your
1781
existing Ice release. For Ice 3.1, use db_recover from Berkeley DB
1782
4.3.29. For Ice 3.2, use db_recover from Berkeley DB 4.5. You can
1783
verify the version of your db_recover tool by running it with the
1788
4. Use the db_recover tool to run recovery on the database
1793
5. Recompile and install the new version of the application.
1795
6. Force a checkpoint using the db_checkpoint utility. Note that you
1796
must use the db_checkpoint utility from Berkeley DB 4.8 when
1797
performing this step.
1799
> db_checkpoint -1 -h db
1801
7. Restart the application.
1807
This section describes APIs that were deprecated in a previous release
1808
and have now been removed. Your application may no longer compile
1809
successfully if it relies on one of these APIs.
1811
The following APIs were removed in Ice 3.3:
1813
* Thread per connection
1815
The primary purpose of this concurrency model was to serialize the
1816
requests received over a connection, either because the application
1817
needed to ensure that requests are dispatched in the order they are
1818
received, or because the application did not want to implement the
1819
synchronization that might be required when using the thread pool
1822
Another reason for using the thread-per-connection concurrency model
1823
is that it was required by the IceSSL plug-ins for Java and C#. This
1824
requirement has been eliminated.
1826
The ability to serialize requests is now provided by the thread pool
1827
and enabled via a new configuration property:
1829
<threadpool>.Serialize=1
1831
Please refer to the "Ice Run Time" chapter of the Ice manual for
1832
more details on this feature.
1834
Aside from the potential semantic changes involved in migrating your
1835
application to the thread pool concurrency model, other artifacts of
1836
thread-per-connection may be present in your application and must be
1839
- The configuration properties Ice.ThreadPerConnection and
1840
<proxy>.ThreadPerConnection
1842
- The proxy methods ice_threadPerConnection and
1843
ice_isThreadPerConnection
1847
The metadata directive "cs:collection" is no longer valid. Use
1848
["clr:collection"] instead.
1852
The following methods have been removed:
1854
- Application::main(int, char*[], const char*, const Ice::LoggerPtr&)
1856
Use Application::main(int, char*[], const InitializationData&)
1859
- initializeWithLogger
1860
- initializeWithProperties
1861
- initializeWithPropertiesAndLogger
1863
Use initialize(int, char*[], const InitializationData&) instead.
1868
Use the equivalent Communicator operations.
1872
The following methods have been removed:
1874
- Application.main(String, String[], String, Logger)
1876
Use Application.main(String, String[], InitializationData)
1879
- initializeWithLogger
1880
- initializeWithProperties
1881
- initializeWithPropertiesAndLogger
1883
Use initialize(String[], InitializationData) instead.
1887
The following methods have been removed:
1889
- Application.main(string, string[], string, Logger)
1891
Use Application.main(string, string[], InitializationData)
1894
- initializeWithLogger
1895
- initializeWithProperties
1896
- initializeWithPropertiesAndLogger
1898
Use initialize(ref string[], InitializationData) instead.
1902
The following methods have been removed:
1904
- initializeWithLogger
1905
- initializeWithProperties
1906
- initializeWithPropertiesAndLogger
1908
Use initialize(args, initializationData) instead.
1913
Use the equivalent Communicator operations.
1917
The following methods have been removed:
1921
- ice_collocationOptimization
1924
These proxy methods were replaced by ones of the form ice_get...,
1925
such as ice_getHash. ice_collocationOptimization is now
1926
ice_getCollocationOptimized.
1934
These proxy methods were replaced by ones that do not use "new" in
1935
their names. For example, ice_newIdentity was replaced by
1940
This property provided a way to install a custom logger
1941
implementation. It has been replaced by a more generalized facility
1942
for installing custom loggers.
1944
Please refer to "Removed APIs" in Section 2 for information on APIs
1945
that were removed in Ice 3.4.
1951
This section discusses APIs and components that are now deprecated.
1952
These APIs will be removed in a future Ice release, therefore we
1953
encourage you to update your applications and eliminate the use of
1954
these APIs as soon as possible.
1956
The following APIs were deprecated in Ice 3.3:
1958
* Sequences as dictionary keys
1960
The use of sequences, and structures containing sequences, as the
1961
key type of a Slice dictionary is now deprecated.
1965
The mappings for the LocalObject type have changed in Java, .NET and
1966
Python. The new mappings are shown below:
1968
Java java.lang.Object
1972
The types Ice.LocalObject and Ice.LocalObjectImpl are deprecated.
1974
* Ice.Trace.Location
1976
This property has been replaced by Ice.Trace.Locator.
1978
* Ice.Default.CollocationOptimization
1980
This property, as well as the corresponding proxy property, have
1981
been replaced by Ice.Default.CollocationOptimized and
1982
<proxy>.CollocationOptimized, respectively.
1984
* <Adapter>.RegisterProcess
1986
This property caused the Ice run time to register a proxy with the
1987
locator registry (e.g., IceGrid) that allowed the process to be shut
1988
down remotely. The new administrative facility (see "New Features")
1989
has replaced this functionality.
1993
As with <Adapter>.RegisterProcess, this property was used primarily
1994
for IceGrid integration and has been replaced by a similar mechanism
1995
in the administrative facility (see "New Features").
2000
These are the names of administrative object adapters in Glacier2
2001
and IcePatch2, respectively. The functionality offered by these
2002
object adapters has been replaced by that of the administrative
2003
facility (see "New Features"), therefore these adapters (and their
2004
associated configuration properties) are deprecated.
2006
Please refer to "Deprecated APIs" in Section 2 for information on APIs
2007
that were deprecated in Ice 3.4.
2010
======================================================================
2011
5. Platform-specific notes
2012
======================================================================
2018
This release supports the operating systems, compilers, and run-time
2019
environments listed in the link below:
2021
http://www.zeroc.com/platforms_3_4_0.html
2027
IPv6 is not currently supported in Java on Windows due to a bug in the
2028
JVM. Refer to the bug database for more information:
2030
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6230761
2036
Mono requires that a system's host name be correctly configured and
2037
that it resolves to an IP address. Otherwise, Mono is unable to
2038
determine the local IP addresses, which causes the creation of object
2039
adapters that listen on INADDR_ANY/0.0.0.0 to fail with an
2046
The IBM JDK ships with limited jurisdiction policy files for the
2047
cryptographic libraries. For more information, including a link to
2048
download unrestricted jurisdiction policy files, see:
2050
http://www.ibm.com/developerworks/java/jdk/security/60/
2052
Once you have downloaded the policy files, unpack them into this
2055
/usr/lib/jvm-private/java-1_6_0-ibm/jce/vanilla
2058
======================================================================
2060
======================================================================
2063
iceca failure on SLES11
2064
-----------------------
2066
The Ice Certificate Authority (iceca) script may fail to import
2067
OpenSSL-generated certificates into a Java keystore. This failure
2068
occurs when using the following command-line options:
2070
iceca java --import ...
2072
The import fails with an error similar to:
2074
lengthTag=127, too big
2076
The error is caused by an incompatibility between the JDK's keytool
2077
and the version of OpenSSL that is included with SLES11 (OpenSSL
2078
0.9.8h). To work around this issue, you can install a newer version of
2079
OpenSSL. Note that it is not necessary to rebuild Ice with the new
2080
OpenSSL version; the only requirement is that you have the new
2081
"openssl" executable in your PATH when running "iceca java --import".
1
See http://doc.zeroc.com/display/Rel/Ice+3.4.2+Release+Notes
added
removed
RELEASE_NOTES
