|
|
| Line 1: |
Line 1: |
| − | == Purpose of this document ==
| + | 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 milestone. You will see it in the build as a plugin named com.ibm.icu. The Eclipse platform will be utilizing the ICU APIs for Eclipse 3.2. |
| | | | |
| − | This page is to document processes and procedures for providing improved coordination of update sites provided by the many Eclipse Projects. It's focus is on the 10 or so projects as part of the
| |
| − | [http://www.eclipse.org/projects/callisto.php Callisto simultaneous release] but some of the information would be helpful to any Eclipse adopter.
| |
| | | | |
| − | Note: as of this initial writing, this document should be taken as a 'proposal', and as its reviewed and discussed and improved by others, it will become a 'plan'. And then, eventually, once the plan seems to be
| + | ==Migration== |
| − | working, it will become a true "process and procedures" document.
| + | This section describes how to adopt ICU4J into your application. |
| | | | |
| − | This document was started because of a cross-project agreement reached at the December, 2005, EMO Architecture Council Meeting. There, through their representatives to the Architecture Council, the projects of
| + | Migration of application code can be done incrementally, meaning full adoption of all ICU4J function is not necessary to reap the benefits of using ICU4J. Migration can be done in the following four sequential steps: |
| − | the Callisto Release agreed to improve the cross-project update experience. The agreement was that I ([[User:David williams|David Williams]]) would coordinate the effort ... but the projects still had to do the work! | + | |
| | | | |
| − | This document is in no way to "take over" any of the Eclipse base project [http://www.eclipse.org/platform/index.php Update Team's] function, proposals, or responsibilities.
| + | 1. <strong>Import changes </strong> |
| | | | |
| − | It is also <b>not to add to their responsibilities</b>. The goal for Callisto release is to use and "push the limits" of the current capabilities and technologies of the Update Manager. Of course, bugs and feature
| + | Some classes need only be replaced with the ICU equivalent class by changing the import statement (i.e. change java.* with com.ibm.icu.*). |
| − | requests may
| + | |
| − | result, and that is fine, but I wanted to be clear this proposal is not for anything fundamentally new ... it is just to document what's already possible, and make sure it is coordinated and carried out with "best
| + | |
| − | practices" in mind.
| + | |
| | | | |
| − | If I understand Wiki's at all committers can use the "talk" feature to provide feedback. Others may open a bugzilla on the Cross Project bugzilla component.
| + | Example: change references of java.text.Collator to com.ibm.icu.text.Collator |
| | | | |
| − | == Use cases ==
| + | This should be done for the following classes: |
| | + | *java.text.BreakIterator |
| | + | *java.text.CollationKey |
| | + | *java.text.Collator |
| | + | *java.text.DateFormat |
| | + | *java.text.DecimalFormat |
| | + | *java.text.NumberFormat |
| | + | *java.text.SimpleDateFormat |
| | + | *java.util.StringTokenizer (see Note) |
| | | | |
| − | There are 3 primary use cases that cross-project, coordinated update sites provide:
| + | 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 |
| | | | |
| − | 1. Allow end-users to install some minimum "platform" and from that be able to use Update Manager to install all of the Callisto release, just by going to just one update site and selecting just one thing.
| + | 2. <strong>Parallel APIs</strong> |
| | | | |
| − | <del>2. Allow committers and developers to install an "SDK" version of Callisto, to be used while developing their own plugins.</del>
| + | 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). |
| | | | |
| − | <del>3. Allow adopters to provide their own update sites, and "point to" appropriate sites to pick up prerequisite features. While there is nothing in this Callisto effort to support this directly, Callisto should serve as a good
| + | Example: replace references of java.lang.Character with class com.ibm.icu.lang.UCharacter |
| − | example of "best practices" for other projects to follow.</del>
| + | |
| | | | |
| − | == Objectives and Constraints ==
| + | The conversion of java.* classes to com.ibm.icu.* classes should be done as follows: |
| | + | *java.text.DateFormatSymbols -> com.ibm.icu.text.DateFormatSymbols |
| | + | *java.text.DecimalFormatSymbols -> com.ibm.icu.text.DecimalFormatSymbols |
| | + | *java.text.MessageFormat -> com.ibm.icu.text.MessageFormat |
| | + | *java.util.Calendar -> com.ibm.icu.util.Calendar |
| | + | *java.util.Currency -> com.ibm.icu.util.Currency |
| | + | *java.util.GregorianCalendar -> com.ibm.icu.util.GregorianCalendar |
| | + | *java.util.SimpleTimeZone -> com.ibm.icu.util.SimpleTimeZone |
| | + | *java.util.TimeZone -> com.ibm.icu.util.TimeZone |
| | + | *java.lang.Character -> com.ibm.icu.lang.UCharacter |
| | + | *java.lang.Character$UnicodeBlock -> com.ibm.icu.lang.UCharacter$UnicodeBlock" |
| | + | *java.text.Format -> com.ibm.icu.text.UFormat |
| | + | *java.util.Locale -> com.ibm.icu.util.ULocale |
| | + | *java.util.ResourceBundle -> com.ibm.icu.util.UResourceBundle |
| | | | |
| − | Besides promoting the use cases given above, there are other objectives and constraints to meet:
| + | 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. |
| | | | |
| | + | 3. <strong>Re-structure</strong> |
| | | | |
| − | === Eclipse.org Infrastructure constraints ===
| + | Some code needs to be re-written to take utilize ICU function. Discovering code that needs to be re-structured in this manner will not be as systematic as in the previous two steps. |
| | | | |
| − | The distribution of Eclipse projects must fit in to the current disk space and "mirror system".
| + | 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)). |
| | | | |
| − | * Disk space.
| + | 4. <strong>Utilize New Features</strong> |
| − | ** JAR files should not be duplicated to avoid wasting bandwidth and disk space on our mirrors.
| + | |
| − | ** The site.xml file can be configured to include JARs from various projects and still work with mirrors. See Distributed Bandwidth, below.
| + | |
| | | | |
| − | * Mirroring.
| + | 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. |
| − | ** Callisto must make the best use of our mirror sites.
| + | |
| − | ** Our mirror sites should have '''at least''' 24-hours of exclusive access to the Callisto files before releasing them to the public. This is done by waiting for Webmaster approval before sending files to download.eclipse.org.
| + | |
| − | ** Webmaster will need to advise mirrors ahead of time, so they can anticipate the rush.
| + | |
| | | | |
| − | * Bandwidth.
| + | Example: the class com.ibm.icu.text.Transliterator |
| − | ** Co-ordinate with the Webmaster to "open the floodgates" on the bandwidth ahead of time.
| + | |
| − | ** R3.1 required additional bandwidth for a foundation-hosted, separate mirror site. We will need this again.
| + | |
| | | | |
| | + | ==Replacement Plug-in== |
| | + | 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: |
| | | | |
| − | === Coordination verus Unification ===
| + | *BreakIterator |
| | + | *CollationKey |
| | + | *Collator |
| | + | *DateFormat |
| | + | *DateFormatSymbols |
| | + | *DecimalFormat |
| | + | *DecimalFormatSymbols |
| | + | *NumberFormat |
| | + | *SimpleDateFormat |
| | + | *StringTokenizer |
| | + | *Calendar |
| | + | *TimeZone |
| | + | *ULocale |
| | + | *MessageFormat |
| | | | |
| − | For ease-of-use, there should be something of a "central site" that should make it easy to "get started" with "all" of Callisto. But, in the Eclipse spirit of allowing projects to "do their own thing" each project should also have their
| |
| − | own
| |
| − | discovery and update sites as well. This allows the central "get started" site to be one-size fits all, but still allow projects to offer even more, special features such as tools, examples, etc., that may not be part of
| |
| − | their "main' deliverables available via Callisto, not to mention have their own schedule for fixes and point releases.
| |
| | | | |
| − | === Update Policies ===
| + | 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). |
| | | | |
| − | Some sites (corporations) can establish an "corporate" update site, which may have its own policies about what updates when, etc. The process and procedures here should do nothing to interfere with that
| + | 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.) |
| − | capability.
| + | |
| | | | |
| − | == Fundamentals ==
| + | <strong>Require-Bundle</strong>: com.ibm.icu |
| | | | |
| − | === Distributed Storage ===
| + | you use the <strong>Import-Package</strong> header to specify your plug-in's dependency on ICU4J (e.g.). |
| | | | |
| − | Each project will still have its own disk space and area on Eclipse, and will still be responsible for providing jarred features and plugins there, as they would for their own update site.
| + | <strong>Import-Package</strong>: com.ibm.icu.text, |
| | + | com.ibm.icu.util |
| | | | |
| − | === Distributed Bandwidth ===
| + | 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. |
| | | | |
| − | The features (and archive tags, if needed) will be specified using the new "find the closest mirror" [https://bugs.eclipse.org/bugs/show_bug.cgi?id=99412#c23 luxury support] provided by the Eclipse.org
| + | ==Bugs in ICU4J== |
| − | download.php script.
| + | Bugs that are found in ICU4J should not be logged against Eclipse products or components, they should be logged against the ICU project at: |
| | | | |
| − | <cite>
| + | http://bugs.icu-project.org/cgi-bin/icu-bugs |
| − | <b>Issue: </b> We (any volunteers?) should begin to collect approximate sizes and make rough estimates of required bandwidth for various scenarios, to make sure our mirroring system will suffice ... or we should panic now!?
| + | |
| | | | |
| − | Here is WebMaster's plan to make this happen:
| |
| − | * Go mirror shopping to get new mirror sites - especially in US and Asia
| |
| − | * Substantially increase bandwidth a few days ahead of release
| |
| − | * Allow mirrors 24 hours to sync up
| |
| − | * Provision a separate, dedicated high-speed mirror within those 24 hours
| |
| − | * Boom
| |
| − | </cite>
| |
| | | | |
| − | === The Get-Started Platform Download === | + | ==More Info== |
| | + | For more information about ICU4J visit the official home page: |
| | | | |
| − | There will be one ZIP provided (by the Eclipse Project), that corresponds to the minimum amount of Eclipse that enables the update manager to work. This is, literally, the Eclipse Platform ... NOT including JDT and
| + | http://www-306.ibm.com/software/globalization/icu/index.jsp |
| − | PDE. This feature will have the Callisto site as its implanted discovery site. It will still have 'eclipse' as its update site as it comes from the Eclipse Project (the update site being where "fixes" can be obtained
| + | |
| − | automatically by update manager). All other features, from all other projects, will have their own project's discovery and update sites implanted in their features, not the Callisto site). The few features available from
| + | |
| − | the central Callisto site will have discovery sites for all 10 Callisto projects.
| + | |
| | | | |
| − | <cite>
| + | ICU open source project site: |
| − | <b>Issue: </b>In this day and age, I'm surprised we do not offer "updates" (or "get started") in the form of a WebStart object. I think we do not only due to people constraints ... so, if there is participation from
| + | |
| − | the community (including the community of Callisto projects :) then we might be able to improve the user's experience so they'd never have to see another zip file again?
| + | |
| − | </cite>
| + | |
| | | | |
| − | <b>Note: </b>We should be explicit that the Callisto Update Site, contrary to the name, must begin with a 3.2 based Platform Feature ... there is no capability planned to update from a 3.1 based environment. Likewise, there are no plans to update from an 3.2 M4 environment to a 3.2 M5 environment. We will plan to test updating from an M5 environment to an M6 environment.
| + | http://icu.sourceforge.net/ |
| − | | + | |
| − | === The User's Experience ===
| + | |
| − | | + | |
| − | ==== The View from Update Manager Dialog ====
| + | |
| − | | + | |
| − | The current plan is, for this Callisto Release, to simply list Features "by Project" [[Image:UpdateProto2.gif]].
| + | |
| − | | + | |
| − | === Central Callisto Sites ===
| + | |
| − | | + | |
| − | ==== Release Site ====
| + | |
| − | For the Callisto releases and milestones, there will be one central "discovery" site, such as
| + | |
| − | http://download.eclipse.org/callisto/releases
| + | |
| − | | + | |
| − | Note: Its desriable to avoid any reliance on "aliases" as it makes mirroring more difficult to manage.
| + | |
| − | | + | |
| − | <del>Also, we should be explicit, there is no plans to provide a big-huge-zip that contains all the Callisto projects ... its expected to be provided entirely via update manager.</del> There has been some recent talk of providing "big zips" made easy to get by the use of a form on a web page, and then the user would get, in one download, a zipped up version of their selections. If this is done, would be handled by the Eclipse Foundation (not this cross-project group).
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ==== Weekly Integration Update Sites ====
| + | |
| − | | + | |
| − | For those projects wishing to participate, there will be a site for integration builds:
| + | |
| − | http://download.eclipse.org/callisto/interim
| + | |
| − | | + | |
| − | ==== Working Staging Area ====
| + | |
| − | | + | |
| − | Lastly, there will be a working directory of
| + | |
| − | http://download.eclipse.org/callisto/staging
| + | |
| − | that is used exclusively by central "Callisto developers" in the days or weeks ahead of the other update "releases" to test that the central features and site.xml is ready before they are copied over to the "public" sites.
| + | |
| − | | + | |
| − | == User Interface Consistency ==
| + | |
| − | | + | |
| − | === Web site consistency ===
| + | |
| − | All update sites will have an "index" file, appropriate for viewing with a web browser ... and we need to work on giving this a consistent look.
| + | |
| − | (currently, some projects have none, some have highly detailed slowly performing ones with jars available for download for some reason I do not understand, but [http://download.eclipse.org/webtools/updates/ some :)] have some really nice looking ones.
| + | |
| − | | + | |
| − | === Update Manager View Consistency ===
| + | |
| − | All update sites will provide a "site.xml" file, with a consistent level of abstraction for separately installable features. (Remember, not literally every feature provided by a project has to be "visible" to the update site
| + | |
| − | user ... many can be "included" as being required by other features, and installed automatically when other features selected).
| + | |
| − | | + | |
| − | These will be consistent and follow the following UI guidelines:
| + | |
| − | | + | |
| − | ; Project Name spelled out, followed by initial in parenthesis, if desired. Such as
| + | |
| − | : Graphical Editing Framework (GEF)
| + | |
| − | : Eclipse Modeling Framework (EMF)
| + | |
| − | | + | |
| − | ; Version numbers only at feature level, not project level categories. Such as
| + | |
| − | : Draw2d 3.2 (not GEF 3.2).
| + | |
| − | | + | |
| − | === Predictable, consistent, long term URL's for update sites ===
| + | |
| − | | + | |
| − | There's currently great inconsistency here. I guess as long as its permanent, and long term, there's no harm. But looks sloppy.
| + | |
| − | | + | |
| − | For example, GEF is in Eclipse, and has no update site of its own. [[https://bugs.eclipse.org/bugs/show_bug.cgi?id=128348 128348]]
| + | |
| − | | + | |
| − | Some sites have a version number in their URL, such as tools/ve/updates/1.0/ and some do not, such as
| + | |
| − | tools/emf/updates/. The latter is correct, and important with the new qualified versioning conventions.
| + | |
| − | | + | |
| − | So, I suggest, this is the time to get consistent, but will need some care and thought to be sure it doesn't "break" anything.
| + | |
| − | | + | |
| − | == Planned Tests and Trial runs ==
| + | |
| − | | + | |
| − | During February, initial test versions will be created to download "all of Callisto" to see how it does,
| + | |
| − | from several parts of the world. Its not expected these will be "usable" versions of Callisto.
| + | |
| − | | + | |
| − | By the end of the M5 period (3/3), there will be a usable version of Callisto available via update manager.
| + | |
| − | (This is the version that can (will) be pointed to during EclipseCon, as an example of what's coming).
| + | |
| − | | + | |
| − | After M5, there will be "updates" (what's the right word for updates to updates?) to the milestones site for each Release Candidate leading up to the release.
| + | |
| − | | + | |
| − | Note: after M5, projects may elect to use the weekly I-build site. But this part of this proposal is sort of experimental, and will need some investigation, to be sure this is no great extra work for anyone ... but the idea is that for developers that are building on top of other features, it's very handy to be able to update pre-reqs in a frequent, easy way. That is, in other words, these "integration sites" are not literally an end-user requirement, so will get a little less attention.
| + | |
| − | | + | |
| − | == Project Responsibilities ==
| + | |
| − | | + | |
| − | This document and this "coordinated effort" is in no way meant to substitute for the projects themselves understanding update manger and update sites and actively
| + | |
| − | contributing [[callisto_update_people | the necessary people]] to ensure the
| + | |
| − | correct end result.
| + | |
| − | | + | |
| − | The following are some requirements placed on the projects participating in Callisto (most should not be anything "new", but some will be, and feasibility and need will have to be evaluated as we go).
| + | |
| − | | + | |
| − | * provide [[project update sites]], with jars, urls, site.xml files, etc. pretty much as has been done before ... but, might be a good time to change past decisions (for example, GEF does not have its own update site, for ... historical reasons, I guess). The Callisto site.xml file will "point to" these project-level update sites, so, basically, each project must have a working update site before Callisto can have a working update site. See [[project update sites]] for more details.
| + | |
| − | | + | |
| − | * provide to "[[callisto build]]" a list of minimum features for inclusion in "runtime" version of Callisto (and, please, minimum for "end users" to take advantage of your functionality). It would include 'end user' documentation, but not 'isv documentation nor JavaDoc.
| + | |
| − | | + | |
| − | <del>* provide to [[User:David williams|David williams]] list of features for inclusion in "SDK" version of Callisto (should be no duplicates with first list, the SDK features should "require" runtime versions, so that someone may install runtime first, then install SDK later, without re-downloading or installing the runtime versions). These SDK features dos not have to be ALL your projects features, but should, at least, include 'source' and 'isv documentation'.</del>
| + | |
| − | | + | |
| − | * provide accurate "feature size" so the update time and progress can be accurate. This is just good practice, but since I've noticed many don't sizes in their updates, I thought I would call it out here, since this will be more important in Callisto.
| + | |
| − | | + | |
| − | * (maybe) provide signed jars, so users get some assurance they are installing verifiable Callisto features. This is more important now, using the "nearest mirror" techniques, since users may not know exactly where the jar is coming from. [I just say "maybe" because I do not think any of us know the technical steps or requirements for this.]
| + | |
| − | | + | |
| − | ** <b>ISSUE: </b> If we have signed jars, it would be "nice" to have a "signed by Eclipse Foundation" corporate certificate, which I mention here, because I think to get such a certificate is a little time consuming (and not free :)
| + | |
| − | | + | |
| − | == Help Wanted ==
| + | |
| − | | + | |
| − | Besides the main deliverables for Callisto, the participating projects are asked to provide some assistance in testing the Callisto update site and, if possible, there are many tools that could be contributed to help. For example,
| + | |
| − | | + | |
| − | * a "peek" tool which doesn't actually update anything, but which could, say, get the date and size headers for all the jars that would be requested by update manager, just for a warm reassuring feeling that all is (still) available as expected in a quick and painless way.
| + | |
| − | | + | |
| − | * specialist to help with security, signed jars would likely be helpful.
| + | |
| − | | + | |
| − | * specialists to help test and tweak update performance would likely not be refused.
| + | |
| − | | + | |
| − | * etc.
| + | |
| − | | + | |
| − | == Bugzilla Queries ==
| + | |
| − | | + | |
| − | The following are some handy bugzilla queries related to update manager.
| + | |
| − | | + | |
| − | [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&classification=Eclipse&product=Platform&component=Update&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&field0-0-0=noop&type0-0-0=noop&value0-0-0=&order=bugs.bug_severity,bugs.target_milestone%2Cbugs.target_milestone%2Cbugs.bug_severity%2Cmap_components.name%2Cbugs.bug_severity%2Cbugs.target_milestone%2Cbugs.bug_severity%2Cmap_components.name%2Cbugs.bug_severity%2Cmap_reporter.login_name%2Cmap_reporter.login_name%2Cmap_components.name%2Cbugs.target_milestone%2Cbugs.bug_severity%2Cbugs.target_milestone%2Cbugs.resolution%2Cmap_components.name%2Cmap_assigned_to.login_name%2Cbugs.bug_status%2Cbugs.target_milestone%2Cbugs.target_milestone%2Cbugs.target_milestone%2Cbugs.bug_severity%2Cbugs.bug_status%2Cbugs.target_milestone%2Cbugs.priority%2Cbugs.bug_id&query_based_on= All Opened]
| + | |
| − | | + | |
| − | | + | |
| − | [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&classification=Eclipse&product=Platform&component=Update&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailreporter1=1&emailtype1=substring&email1=david_williams&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= All Opened by David Williams :) since starting to play with Callisto Updates.]
| + | |
| − | | + | |
| − | == Tips and Tricks ==
| + | |
| − | | + | |
| − | In addition to the written works in the reference section, I often some across little tidbits in bug reports, newsgroups, etc., and hope we can collect some of them on our [[Callisto Build and Update Tips and Tricks]] page. (So I can find them in the future :)
| + | |
| − | | + | |
| − | == Related Links for Further Enjoyable Reading and Reference ==
| + | |
| − | | + | |
| − | [http://help.eclipse.org/help31/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/product_update.htm Basics of Update Sites]
| + | |
| − | | + | |
| − | [http://www.eclipse.org/articles/Article-Update/keeping-up-to-date.html How To Keep Up To Date]
| + | |
| − | | + | |
| − | [http://www.eclipse.org/eclipse/platform-core/documents/plugin-versioning.html Plugin Versioning Proposal]
| + | |
| − | | + | |
| − | [http://www.eclipse.org/eclipse/platform-core/documents/update.html Update Site Proposal]
| + | |
| − | | + | |
| − | [http://www.eclipse.org/eclipse/platform-core/documents/3.1/run_from_jars.html Jarring Plugins]
| + | |
| − | | + | |
| − | [[Development_Conventions_and_Guidelines]]
| + | |
| − | | + | |
| − | [[JAR_Signing]]
| + | |
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 milestone. You will see it in the build as a plugin named com.ibm.icu. The Eclipse platform will be utilizing the ICU APIs for Eclipse 3.2.
Migration of application code can be done incrementally, meaning full adoption of all ICU4J function is not necessary to reap the benefits of using ICU4J. Migration can be done in the following four sequential steps:
1. Import changes
Some classes need only be replaced with the ICU equivalent class by changing the import statement (i.e. change java.* with com.ibm.icu.*).
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
2. Parallel APIs
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).
Example: replace references of java.lang.Character with class com.ibm.icu.lang.UCharacter
The conversion of java.* classes to com.ibm.icu.* classes should be done as follows:
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.
3. Re-structure
Some code needs to be re-written to take utilize ICU function. Discovering code that needs to be re-structured in this manner will not be as systematic as in the previous two steps.
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)).
4. Utilize New Features
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.
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 (com.ibm.icu.base) from the build page from which you obtained your Eclipse build, remove the com.ibm.icu 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:
If you choose to adopt ICU4J, it is recommended that, in your plug-in manifest file, instead of using the Require-Bundle header to specify the dependency on ICU4J (e.g.)
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.
Bugs that are found in ICU4J should not be logged against Eclipse products or components, they should be logged against the ICU project at:
