Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between pages "ICU4J" and "Adaptor Hooks"

(Difference between pages)
(Migration)
 
 
Line 1: Line 1:
ICU4J is a set of Java libraries that provides more comprehensive support for Unicode, software globalization, and internationalization. In order to provide this functionality to the Eclipse community, ICU4J was added to the Eclipse platform build for the 3.2 M4 milestoneYou will see it in the build as a plugin named com.ibm.icuThe Eclipse platform will be utilizing the ICU APIs for Eclipse 3.2.
+
== Overview ==
 +
Since Eclipse 3.0 the Framework Adaptor API has been available in the Equinox OSGi FrameworkA framework adaptor implementation is called upon by the Equinox OSGi Framework to perform a number of tasksA framework adaptor may be used to add functionality to the framework.
  
 +
A single framework adaptor is specified when the framework is launched.  By default in Eclipse 3.0 this is set to the EclipseAdaptor.  In order to add new functionality in an adaptor in Eclipse 3.0 and 3.1 it is required that the adaptor implementation either re-implement the complete framework adaptor API or extend one of the existing framework adaptor implementations.  This makes it impossible for two parties to add new functionality to the framework in separate adaptors at the same time because the Equinox OSGi Framework can only be configured to use one adaptor.
  
==Migration==
+
In Eclipse 3.2 a new hookable adaptor has been included that is used by default as the framework adaptor.  The framework adaptor API has remained unchanged for the most part in Eclipse 3.2.  What has changed is the actual implementation of the adaptor API.  A new implementation of the adaptor API is now included which provides hooks that others can implement to provide functionality to the adaptor implementation.
This section describes how to adopt ICU4J into your application.
+
  
Migration of application code can be done incrementally, meaning full adoption of all ICU4J function is not necessary to reap the benefits of using ICU4JMigration can be done in the following four sequential steps:
+
== Hookable Adaptor ==
 +
The hookable adaptor is implemented in the package org.eclipse.osgi.baseadaptor.  This adaptor implementation provides all of the default behavior required of a FrameworkAdaptor to provide an OSGi R4 compliant Framework.  It also provides many hooks that allow others to insert additional functionality into the framework through what are called framework extension bundlesSee the OSGi Core Specification chapter 3.15 "Extension Bundles" for more information.
  
1. <strong>Import changes </strong>
+
Framework extension bundles are fragments of the system bundle (org.eclipse.osgi).  As a fragment they can provide extra classes which the framework can use.  A framework extension bundle can define a set of hook implementations that are configured with the hookable adaptor (using a hookconfigurators.properties file). 
  
Some classes need only be replaced with the ICU equivalent class by changing the import statement (i.e. change java.* with com.ibm.icu.*).
+
=== The Base Adaptor ===
 +
The class org.eclipse.osgi.baseadaptor.BaseAdaptor implements the interface org.eclipse.osgi.framework.adaptor.FrameworkAdaptor. This class is used by default as the adaptor of the framework.  You should avoid extending this class, instead you should use hook implementations to add functionality to the BaseAdaptor.
  
Example: change references of java.text.Collator to com.ibm.icu.text.Collator
+
In some cases it may be impossible to do what you want with the current set of adaptor hooks. In this case you may be forced to extend the BaseAdaptor class to provide your own adaptor implementation. If you find yourself in this situation then you should open a bug against Framework Equinox requesting a new hook method or interface.
  
This should be done for the following classes:
+
=== The Hook Registry ===
*java.text.BreakIterator
+
The hook registry is implemented in the class org.eclipse.osgi.baseadaptor.HookRegistry. The hook registry is used to store all the hooks configured in the framework. When the hook registry is initialized it will discover all the hook configurators installed in the framework and will call on them to add hooks to the registry. The BaseAdaptor uses the hook registry at runtime to lookup and use the different hooks configured with the registry.
*java.text.CollationKey
+
*java.text.Collator
+
*java.text.DateFormat
+
*java.text.DecimalFormat
+
*java.text.NumberFormat
+
*java.text.SimpleDateFormat
+
*java.util.StringTokenizer (see Note)
+
  
Note: The Eclipse SDK did not adopt ICU's version of StringTokenizer at this time as it will cause a performance degradation vs. the default java.* implementation
+
==== Hook Configurators ====
 +
Hook configurators must implement the org.eclipse.osgi.baseadaptor.HookConfigurator interface.  Hook configurators can add one or more hook implementations to the hook registry using the various add methods on the registry.
  
2. <strong>Parallel APIs</strong>
+
==== Discovering Hook Configurators ====
 +
In order for a hook configurator to be discovered by the hook registry its implementation must be accessable by the framework's classloader.  This implies that hook configurators must be built into the framework itself (org.eclipse.osgi) or be supplied by a framework extension bundle.  Again a framework extension bundle is really just a fragment to Framework (i.e org.eclipse.osgi or the System Bundle).
  
In this case, you will want to use the corresponding classes and API’s in place of the ones that are included in the JDK (in the java.* packages).
+
A hook configurator also must be declared in one of the following ways to indicate to the hook registry which classes should be loaded as hook configurators.
  
Example: replace references of java.lang.Character with class com.ibm.icu.lang.UCharacter
+
===== hookconfigurators.properties files =====
 +
A hookconfigurators.properties file can be used to declare a list of hook configator classes. The key hook.configurators is used in a hook configurators properties file to specify a comma separated list of fully qualified hook configurator classes.  For example, the Equinox Framework (org.eclipse.osgi) is shipped with a default set of hook configurators specified a hookconfigurators.properties file included in the org.eclipse.osgi.jar:
  
The conversion of java.* classes to com.ibm.icu.* classes should be done as follows:
+
<code>
*java.text.DateFormatSymbols -> com.ibm.icu.text.DateFormatSymbols
+
hook.configurators=
*java.text.DecimalFormatSymbols -> com.ibm.icu.text.DecimalFormatSymbols
+
    org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator,
*java.text.MessageFormat -> com.ibm.icu.text.MessageFormat
+
    org.eclipse.osgi.internal.baseadaptor.DevClassLoadingHook,
*java.util.Calendar -> com.ibm.icu.util.Calendar
+
    org.eclipse.core.runtime.internal.adaptor.EclipseStorageHook,
*java.util.Currency -> com.ibm.icu.util.Currency
+
    org.eclipse.core.runtime.internal.adaptor.EclipseLogHook,
*java.util.GregorianCalendar -> com.ibm.icu.util.GregorianCalendar
+
    org.eclipse.core.runtime.internal.adaptor.EclipseErrorHandler,
*java.util.SimpleTimeZone -> com.ibm.icu.util.SimpleTimeZone
+
    org.eclipse.core.runtime.internal.adaptor.EclipseAdaptorHook,
*java.util.TimeZone -> com.ibm.icu.util.TimeZone
+
    org.eclipse.core.runtime.internal.adaptor.EclipseClassLoadingHook,
*java.lang.Character ->  com.ibm.icu.lang.UCharacter
+
    org.eclipse.core.runtime.internal.adaptor.EclipseLazyStarter,
*java.lang.Character$UnicodeBlock -> com.ibm.icu.lang.UCharacter$UnicodeBlock"
+
    org.eclipse.core.runtime.internal.stats.StatsManager,
*java.text.Format -> com.ibm.icu.text.UFormat
+
    org.eclipse.osgi.internal.verifier.SignedBundleHook
*java.util.Locale -> com.ibm.icu.util.ULocale
+
</code>
*java.util.ResourceBundle -> com.ibm.icu.util.UResourceBundle
+
  
Note: classes UCharacter, UResourceBundle, and UFormat are not implemented in the replacement plug-in (see below) so if your application’s code needs to work with both the replacement plug-in and the real ICU4J plug-in then you will not be able to adopt these classes at this time.
+
Quite a few hook configurators are automatically enabled by default withing the Equinox Framework.  The only hook configurator required for a fully functional OSGi R4 Framework is the org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator.  All other configurators declared above add extra functionality needed by eclipse and can be disabled.
  
3. <strong>Re-structure</strong>
+
Extension bundles may provide their own hookconfigurators.properties file to specify additional hook configurators.  The hook registry will discover all hookconfigurator.properties files on its classpath and will merge all declared configurator classes into one list.
  
Some code needs to be re-written to take utilize ICU functionDiscovering code that needs to be re-structured in this manner will not be as systematic as in the previous two steps.
+
===== osgi.hook.configurators property =====
 +
The osgi.hook.configurators configuration property is used to specify the list of hook configuratorsIf this property is set then the list of configurators specified will be the only configurators used.  If this property is set then the hookconfigurators.properties files will not be processed for additional configurators.  This property can be used in a config.ini to lock down the set of configurators to a specific set.
  
Example: use com.ibm.icu.text.BreakIterator to locate boundaries in text instead of iterating over a string and using java.lang.Character.isLetterOrDigit(string.charAt(idx)).
+
===== osgi.hook.configurators.include property =====
 +
The osgi.hook.configurators.include configuration property is used to add additional hook configurators.  This is helpful for configuring optional hook configurators.  Hooks that should be enabled by default should be included in a hookconfigurators.properties file. This property is ignored if the osgi.hook.configurators is set.
  
4. <strong>Utilize New Features</strong>
+
===== osgi.hook.configurators.exclude property =====
 +
The osgi.hook.configurators.include configuration property is used to exclude any hook configurators.  This is helpful for disabling hook configurators that are specified in hook configurator properties files.  This property is ignored if the osgi.hook.configurators is set.
  
ICU adds additional function in some areas that is not provided by the JDK.  In this case, new code would need to be written to take advantage of these new features. 
+
== Hook interfaces ==
  
Example: the class com.ibm.icu.text.Transliterator
+
=== Adaptor Hook ===
  
==Replacement Plug-in==
+
=== Bundle File Factory Hook ===
The Eclipse SDK will be adopting the ICU4J APIs for Eclipse 3.2.  The addition of the ICU4J plug-in adds on the order of 3MB worth of code.  Some applications may not want to absorb ICU4J if the priority is size over adopting the ICU4J function.  If this is the case for your application, you can download the replacement plug-in (<strong>com.ibm.icu.base</strong>) from the build page from which you obtained your Eclipse build, remove the <strong>com.ibm.icu</strong> plug-in and its source counterpart, and drop in the replacement plug-in.  This is required because the Platform adopted the ICU APIs for 3.2 and so just removing the ICU plug-in will result in compilation errors.  The replacement plug-in is about 100KB in size and simply calls through to the java.* packages (default JDK implementation) of the most commonly used classes and APIs in ICU4J.  The classes that are implemented in the replacement plug-in are as follows:
+
  
*BreakIterator
+
=== Bundle File Wrapper Factory Hook ===
*CollationKey
+
*Collator
+
*DateFormat
+
*DateFormatSymbols
+
*DecimalFormat
+
*DecimalFormatSymbols
+
*NumberFormat
+
*SimpleDateFormat
+
*StringTokenizer
+
*Calendar
+
*TimeZone
+
*ULocale
+
*MessageFormat
+
  
 +
=== Bundle Watcher Hook ===
  
If your application needs to be compatible between both the ICU4J plug-in and the replacement plug-in (most often for size reasons), we recommend you only use the API in the classes from this list.  If ICU4J is guaranteed to always be present in the application then you can safely use any of the ICU4J APIs.  The replacement plug-in will be built separately and available as a download on the build pages, but this is still work in progress.  You can however, start using the ICU4J APIs since the ICU4J plug-in is currently in the SDK build as of M4 (and beyond).
+
=== Class Loading Hook ===
  
If you choose to adopt ICU4J, it is recommended that, in your plug-in manifest file, instead of using the <strong>Require-Bundle</strong> header to specify the dependency on ICU4J (e.g.)
+
=== Class Loading Stats Hook ===
  
<strong>Require-Bundle</strong>: com.ibm.icu
+
=== Storage Hook ===
  
you use the <strong>Import-Package</strong> header to specify your plug-in's dependency on ICU4J (e.g.).
+
== Bundle Files ==
  
<strong>Import-Package</strong>: com.ibm.icu.text,
+
== Class Loaders ==
com.ibm.icu.util
+
  
This is to ensure you will not encounter compile or runtime errors if you decide to use the replacement plug-in instead of the full ICU4J plug-in, or vice-versa.
+
== Examples ==
 
+
==Bugs in ICU4J==
+
Bugs that are found in ICU4J should not be logged against Eclipse products or components, they should be logged against the ICU project at:
+
 
+
http://bugs.icu-project.org/cgi-bin/icu-bugs
+
 
+
 
+
==More Info==
+
For more information about ICU4J visit the official home page:
+
 
+
http://www-306.ibm.com/software/globalization/icu/index.jsp
+
 
+
ICU open source project site:
+
 
+
http://icu.sourceforge.net/
+

Revision as of 11:48, 22 April 2006

Overview

Since Eclipse 3.0 the Framework Adaptor API has been available in the Equinox OSGi Framework. A framework adaptor implementation is called upon by the Equinox OSGi Framework to perform a number of tasks. A framework adaptor may be used to add functionality to the framework.

A single framework adaptor is specified when the framework is launched. By default in Eclipse 3.0 this is set to the EclipseAdaptor. In order to add new functionality in an adaptor in Eclipse 3.0 and 3.1 it is required that the adaptor implementation either re-implement the complete framework adaptor API or extend one of the existing framework adaptor implementations. This makes it impossible for two parties to add new functionality to the framework in separate adaptors at the same time because the Equinox OSGi Framework can only be configured to use one adaptor.

In Eclipse 3.2 a new hookable adaptor has been included that is used by default as the framework adaptor. The framework adaptor API has remained unchanged for the most part in Eclipse 3.2. What has changed is the actual implementation of the adaptor API. A new implementation of the adaptor API is now included which provides hooks that others can implement to provide functionality to the adaptor implementation.

Hookable Adaptor

The hookable adaptor is implemented in the package org.eclipse.osgi.baseadaptor. This adaptor implementation provides all of the default behavior required of a FrameworkAdaptor to provide an OSGi R4 compliant Framework. It also provides many hooks that allow others to insert additional functionality into the framework through what are called framework extension bundles. See the OSGi Core Specification chapter 3.15 "Extension Bundles" for more information.

Framework extension bundles are fragments of the system bundle (org.eclipse.osgi). As a fragment they can provide extra classes which the framework can use. A framework extension bundle can define a set of hook implementations that are configured with the hookable adaptor (using a hookconfigurators.properties file).

The Base Adaptor

The class org.eclipse.osgi.baseadaptor.BaseAdaptor implements the interface org.eclipse.osgi.framework.adaptor.FrameworkAdaptor. This class is used by default as the adaptor of the framework. You should avoid extending this class, instead you should use hook implementations to add functionality to the BaseAdaptor.

In some cases it may be impossible to do what you want with the current set of adaptor hooks. In this case you may be forced to extend the BaseAdaptor class to provide your own adaptor implementation. If you find yourself in this situation then you should open a bug against Framework Equinox requesting a new hook method or interface.

The Hook Registry

The hook registry is implemented in the class org.eclipse.osgi.baseadaptor.HookRegistry. The hook registry is used to store all the hooks configured in the framework. When the hook registry is initialized it will discover all the hook configurators installed in the framework and will call on them to add hooks to the registry. The BaseAdaptor uses the hook registry at runtime to lookup and use the different hooks configured with the registry.

Hook Configurators

Hook configurators must implement the org.eclipse.osgi.baseadaptor.HookConfigurator interface. Hook configurators can add one or more hook implementations to the hook registry using the various add methods on the registry.

Discovering Hook Configurators

In order for a hook configurator to be discovered by the hook registry its implementation must be accessable by the framework's classloader. This implies that hook configurators must be built into the framework itself (org.eclipse.osgi) or be supplied by a framework extension bundle. Again a framework extension bundle is really just a fragment to Framework (i.e org.eclipse.osgi or the System Bundle).

A hook configurator also must be declared in one of the following ways to indicate to the hook registry which classes should be loaded as hook configurators.

hookconfigurators.properties files

A hookconfigurators.properties file can be used to declare a list of hook configator classes. The key hook.configurators is used in a hook configurators properties file to specify a comma separated list of fully qualified hook configurator classes. For example, the Equinox Framework (org.eclipse.osgi) is shipped with a default set of hook configurators specified a hookconfigurators.properties file included in the org.eclipse.osgi.jar:

hook.configurators= 
   org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator,
   org.eclipse.osgi.internal.baseadaptor.DevClassLoadingHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseStorageHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseLogHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseErrorHandler,
   org.eclipse.core.runtime.internal.adaptor.EclipseAdaptorHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseClassLoadingHook,
   org.eclipse.core.runtime.internal.adaptor.EclipseLazyStarter,
   org.eclipse.core.runtime.internal.stats.StatsManager,
   org.eclipse.osgi.internal.verifier.SignedBundleHook

Quite a few hook configurators are automatically enabled by default withing the Equinox Framework. The only hook configurator required for a fully functional OSGi R4 Framework is the org.eclipse.osgi.internal.baseadaptor.BaseHookConfigurator. All other configurators declared above add extra functionality needed by eclipse and can be disabled.

Extension bundles may provide their own hookconfigurators.properties file to specify additional hook configurators. The hook registry will discover all hookconfigurator.properties files on its classpath and will merge all declared configurator classes into one list.

osgi.hook.configurators property

The osgi.hook.configurators configuration property is used to specify the list of hook configurators. If this property is set then the list of configurators specified will be the only configurators used. If this property is set then the hookconfigurators.properties files will not be processed for additional configurators. This property can be used in a config.ini to lock down the set of configurators to a specific set.

osgi.hook.configurators.include property

The osgi.hook.configurators.include configuration property is used to add additional hook configurators. This is helpful for configuring optional hook configurators. Hooks that should be enabled by default should be included in a hookconfigurators.properties file. This property is ignored if the osgi.hook.configurators is set.

osgi.hook.configurators.exclude property

The osgi.hook.configurators.include configuration property is used to exclude any hook configurators. This is helpful for disabling hook configurators that are specified in hook configurator properties files. This property is ignored if the osgi.hook.configurators is set.

Hook interfaces

Adaptor Hook

Bundle File Factory Hook

Bundle File Wrapper Factory Hook

Bundle Watcher Hook

Class Loading Hook

Class Loading Stats Hook

Storage Hook

Bundle Files

Class Loaders

Examples

Back to the top