platform-update-home/doc/eclipse_update_packaging.html

Parent Directory | Revision Log | Patch

-revision 1.14, Wed Jan 15 15:30:07 2003 UTC
+revision 1.15, Wed Jan 22 14:30:17 2003 UTC
 Line 9
    <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
    <title>Eclipse Platform: Installation and Update</title>
  </head>
    <body>
  <h1> Eclipse Platform<br>
            Update Packaging Conventions</h1>
-           <font size="-1">Revision Date: 01/15/2003 9:33AM - Version: 2.0.17</font><br>
+            <font size="-1">Revision Date: 01/22/2003 9:56AM - Version: 2.0.18</font><br>
           <a href="../../../../../hglegal.htm"><img src="ngibmcpy.gif"
   border="0" height="12" width="195">
           </a>
  <p><b>Change History:</b> </p>
  <ul>
+             <li><small>2.0.18</small></li>
+   <ul>
+     <li><small>added &lt;feature plugin=""&gt;</small></li>
+   </ul>
             <li><small>2.0.17</small></li>
    <ul>
      <li><small>added $os$,$ws$,$arch$ and $nl$ for copyright, description
  and license URL tag in feature.<br>
        </small></li>
    </ul>
    <li><small>2.0.16</small>     <small><br>
            </small>
-Line 145
+Line 150
           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Framework">Framework</a>
      <br>
           <a href="#Packaging_Conventions">Packaging Conventions</a>  <br>
-          &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Feature_Archive">Feature
+           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a
-     Archive</a>  <br>
+  href="#Feature_Archive">Feature     Archive</a>  <br>
-          &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Plug-In_Archive">Plug-In
+           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a
-     Archive</a>  <br>
+  href="#Plug-In_Archive">Plug-In     Archive</a>  <br>
           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="#Packaging_NL">Packaging
     NL</a>   <br>
           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a
-Line 193
+Line 198
      Manager Agreement</a> " for additional legal information governing the
   use   of the Eclipse update manager function.
  <h3> <a name="Changes_from_R1.0"></a> Changes from R1.0</h3>
-           This section describes the major design changes from the R1.0 Installation
+            This section describes the major design changes from the R1.0
-      and Update support and supplies rationale for each design change.
+ Installation      and Update support and supplies rationale for each design
+ change.
  <ul>
            <li> <b>extendable framework</b></li>
             <br>
-Line 214
+Line 219
   up of plug-ins from "sub-features", the top-level feature "manifest" must
   be fully resolved at packaging time. <li> <b>default feature archive format</b></li>
             <br>
-          R1.0 components were packaged as a single Java .jar containing the
+           R1.0 components were packaged as a single Java .jar containing
-  component    manifest as well as the actual plug-in files. The problem with
+ the   component    manifest as well as the actual plug-in files. The problem
-  this approach    is lack of granularity at download time. In R2.0, the feature
+ with   this approach    is lack of granularity at download time. In R2.0,
-  archive consists    of multiple separate .jars - one .jar per plug-in and
+ the feature   archive consists    of multiple separate .jars - one .jar per
-  fragment, plus one   .jar for the actual feature information. The Installation
+ plug-in and   fragment, plus one   .jar for the actual feature information.
-  and Update support   selectively downloads only those jars required for the
+ The Installation   and Update support   selectively downloads only those
-  installation. <li>    <b>site map</b></li>
+ jars required for the  installation. <li>    <b>site map</b></li>
             <br>
           Default Eclipse update server must contain a <i>site map</i> file
-  (site.xml).     This is an evolution of the R1.0 install.index support.
+  (site.xml).     This is an evolution of the R1.0 install.index support. The
- The  rationale for    using a structured site defined by the map rather than
+  rationale for    using a structured site defined by the map rather than a
- a  "free form" web   site, is the ability to present a consistent installation
+  "free form" web   site, is the ability to present a consistent installation
   experience for  the user. Also, this provides the necessary structure for
   discovery of available   updates. Additional support for "free form" browsing
   may be considered in   future work.    <li> <b>using native install/ uninstall</b></li>
-Line 245
+Line 250
             <br>
           In many cases the standard installation handling supplied by Eclipse
    is  not be sufficient to handle various custom requirements. To accommodate
-    this,  R2.0 Eclipse supports custom install handlers packaged as part
+    this,  R2.0 Eclipse supports custom install handlers packaged as part of
- of   the feature  and executed during the feature installation. <li> <b>path
+   the feature  and executed during the feature installation. <li> <b>path
  naming   conventions</b></li>
             <br>
           R1.0 mandated the use of the various identifiers and versions inside
-   the   packaged archives (eg. directory path names for plug-ins). This approach
+    the   packaged archives (eg. directory path names for plug-ins). This
-     has proven to be ackward and error prone. In 2.0, the packaging requirements
+ approach     has proven to be ackward and error prone. In 2.0, the packaging
-     no longer mandate that path names of packaged files precisely reflect
+ requirements     no longer mandate that path names of packaged files precisely
- the    contained identifiers and versions. The properly identified install
+ reflect the    contained identifiers and versions. The properly identified
- subdirectories    are created by the Eclipse support during the installation
+ install subdirectories    are created by the Eclipse support during the installation
  and update process     based on the archive content (rather than explicit
  jar path structure set    up at packaging time)
  </ul>
  <h3> <a name="Concepts"></a> Concepts</h3>
            <b>Plug-in</b> <br>
-          Eclipse developers build plug-ins. Plug-ins are the base units of
+           Eclipse developers build plug-ins. Plug-ins are the base units
-  execution     recognized by the Eclipse runtime environment. In general,
+ of  execution     recognized by the Eclipse runtime environment. In general,
  plug-ins are   not exposed to users that select function during installation
  or update.  The reason is that plug-in boundaries are established by developers
  for development    reasons (like function reuse) and present the wrong level
-Line 282
+Line 287
       to a form suitable for packaging and installation. Typically it means
   creation    of the runtime .jar(s) and removing any development-time files
   (source,  exposed .class files, etc). It also means updating the plugin.xml
-  manifest  with the formal plug-in version and reflecting the version in
+  manifest  with the formal plug-in version and reflecting the version in the
- the  plug-in  directory name (see "Concurrent Plug-In Version Support" for
+  plug-in  directory name (see "Concurrent Plug-In Version Support" for details).
- details).  </p>
+  </p>
  <p><b>Plug-in Fragment</b> <br>
           Plug-in Fragments (or simply Fragments) allow independent packaging
-Line 315
+Line 320
    that   allows custom implementations to be supplied for its key elements.
    In particular,    the following can be supplied:
  <ul>
-           <li> concrete implementations of feature (IFeature interface) that
+            <li> concrete implementations of feature (IFeature interface)
-   can   be used to support alternate packaging schemes. New concrete feature
+ that   can   be used to support alternate packaging schemes. New concrete
-   types   are  registere via the "org.eclipse.update.featureTypes" extension
+ feature   types   are  registere via the "org.eclipse.update.featureTypes"
-   point.</li>
+ extension   point.</li>
-            <li> concrete implementations of site (ISite interface) that can
+             <li> concrete implementations of site (ISite interface) that
-  be  used  to support alternate site layout, or site behavior. New concrete
+ can   be  used  to support alternate site layout, or site behavior. New concrete
   site  types   are registered via the "org.eclipse.update.siteTypes" extension
    point.</li>
             <li> each feature can specify a custom install handler as part
  of  its   feature  manifest. Install handlers (IInstallHandler interface)
- are  dynamically   invoked as part of the installation process to handle non-plugin
+  are  dynamically   invoked as part of the installation process to handle
-  data, plus   perform other custom processing allowed by the framework.</li>
+ non-plugin  data, plus   perform other custom processing allowed by the framework.</li>
  </ul>
-           Eclipse provides default implementations of feature and site. These
+            Eclipse provides default implementations of feature and site.
-   are  described in the rest of this document. <br>
+ These    are  described in the rest of this document. <br>
           &nbsp;
  <table border="1" cols="1" width="100%">
            <tbody>
               <tr>
            <td><b>Note: <i>The reminder of this document describes the default
-   concrete   implementation of the framework delivered with Eclipse. It specifies
+    concrete   implementation of the framework delivered with Eclipse. It
-   the  structure of the default feature implementation, as well as the default
+ specifies    the  structure of the default feature implementation, as well
-    site  implementation, plus the corresponding xml files (feature.xml and
+ as the default    site  implementation, plus the corresponding xml files
-  site.xml).   Providers of alternate concrete implementations can extend&nbsp;
+ (feature.xml and  site.xml).   Providers of alternate concrete implementations
-  parts or   all of the default Eclipse implementation. This includes providing
+ can extend&nbsp;  parts or   all of the default Eclipse implementation. This
-  a mechanism   for dynamic computation of the site map (site.xml)</i></b></td>
+ includes providing  a mechanism   for dynamic computation of the site map
+ (site.xml)</i></b></td>
            </tr>
    </tbody>
-Line 356
+Line 362
             <li> zero or more jars containing the feature plug-ins. These
  are   refered   to as the "<b>plug-in archives</b>"</li>
             <li> zero or more non-plug-in files associated with the feature.
-  They   are used by feature custom install handlers and contain data not interpreted
+   They   are used by feature custom install handlers and contain data not
-     by Eclipse</li>
+ interpreted     by Eclipse</li>
  </ul>
  <h3> <a name="Feature_Archive"></a> Feature Archive</h3>
            The feature packaging information is placed into a separate Java
-  .jar.    Standard Java jar facilities are used for constructing feature
+  .jar.    Standard Java jar facilities are used for constructing feature archives.
- archives.    Feature archives reference separately packaged plug-in archives
+    Feature archives reference separately packaged plug-in archives (see next
- (see next    section) and non-plug-in files.
+    section) and non-plug-in files.
  <p>Features are identified using a structured identifier based on the provider
       internet domain name. For example, organization eclipse.org may produce
     feature org.eclipse.javatooling. The character set used for feature identifiers
-Line 386
+Line 392
           <tt>my_feature.jar</tt> </p>
  <p>Internally, each feature archive is packaged relative to its feature directory
-     (but not including the directory path element). The archive has the following
+      (but not including the directory path element). The archive has the
-     structure </p>
+ following      structure </p>
  <p><tt>feature.xml</tt> <br>
-          <tt>feature&lt;_locale&gt;.properties (see "Translated Feature Information")</tt>
+           <tt>feature&lt;_locale&gt;.properties (see "Translated Feature
-      <br>
+ Information")</tt>       <br>
           <tt>other feature files and subdirectories (TBD)</tt> <br>
           <tt>META-INF/</tt> <br>
           <tt>&nbsp;&nbsp;&nbsp; Java jar manifest and security files</tt>
-Line 401
+Line 407
  <p><tt>&lt;?xml encoding="ISO-8859-1"?&gt;</tt> </p>
- <p><tt>&lt;!ELEMENT feature (install-handler?, description?, copyright?,
+ <p><tt>&lt;!ELEMENT feature (install-handler?, description?, copyright?, license?,
- license?, url?, includes*, requires?, plugin*, data*)&gt;</tt> <br>
+ url?, includes*, requires?, plugin*, data*)&gt;</tt> <br>
           <tt>&lt;!ATTLIST feature</tt> <br>
           <tt>&nbsp;&nbsp;&nbsp; id&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
       CDATA #REQUIRED</tt> <br>
-Line 426
+Line 432
       CDATA #IMPLIED</tt> <br>
           <tt>&nbsp;&nbsp;&nbsp; primary&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
   (true    | false) "false"</tt> <br>
-          <tt>&nbsp;&nbsp;&nbsp; application&nbsp;&nbsp; CDATA #IMPLIED</tt>
+           <tt>&nbsp;&nbsp;&nbsp; application&nbsp;&nbsp; CDATA #IMPLIED<br>
-  <br>
+ </tt>   &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; <tt>plugin&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
+ &nbsp;CDATA #IMPLIED</tt><br>
           <tt>&gt;</tt> </p>
  <p><tt>&lt;!ELEMENT install-handler EMPTY&gt;</tt> <br>
-Line 571
+Line 578
  should only    be installed on one of the specified systems. If this attribute
  is not specified,   the feature can be installed on all systems (portable
  implementation).  This   information is used as a hint by the installation
- and update support  (user   can force installation of feature regardless of
+  and update support  (user   can force installation of feature regardless
- this setting).</li>
+ of this setting).</li>
             <li> ws - optional windowing system specification. A comma-separated
     list  of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
      . Indicates this feature should only be installed on one of the specified
-Line 581
+Line 588
   a  hint by the installation and update support (user can force installation
    of feature regardless of this setting).</li>
             <li> nl - optional locale specification. A comma-separated list
-  of  locale   designators defined by Java. Indicates this feature should
+  of  locale   designators defined by Java. Indicates this feature should only
- only  be installed   on a system running with a compatible locale (using
+  be installed   on a system running with a compatible locale (using Java
- Java locale-matching    rules). If this attribute is not specified, the feature
+ locale-matching    rules). If this attribute is not specified, the feature
  can be installed   on all systems (language-neutral implementation). This
  information is used   as a hint by the installation and update support (user
  can force installation    of feature regardless of this setting).</li>
             <li> colocation-affinity - optional reference to another feature
-  identifier    used to select the default installation location for this feature.
+   identifier    used to select the default installation location for this
-  When  this feature is being installed as a new feature (no other versions
+ feature.  When  this feature is being installed as a new feature (no other
-  of it  are installed), an attempt is made to install this feature in the
+ versions  of it  are installed), an attempt is made to install this feature
- same installation    location as the referenced feature.</li>
+ in the same installation    location as the referenced feature.</li>
             <li> primary - optional indication specifying whether this feature
    can   be used as a <a href="#Dominant_Feature">primary feature</a> . Default
    if        <i>false</i> (not a primary feature).</li>
-Line 600
+Line 607
   href="#Dominant_Feature"> primary feature</a> . The application identifier
      must represent a valid application registered in the <tt>org.eclipse.core.runtime.applications</tt>
      extension point. Default is <tt>org.eclipse.ui.workbench</tt>.</li>
+     <li> plugin- optional identifier of the primary plugin associated with
+ this <a
+  href="file:///C:/OTI/workspace/plugins/platform-update-home/doc/eclipse_update_packaging.html#Dominant_Feature">primary
+ feature</a>. The primary plugin carries branding information. If the plugin
+ attribute is not declared, the primary plugin identifier used will be the
+ same as the feature identifier. </li>
    </ul>
             <li> &lt;install-handler&gt;</li>
    <ul>
            <li> library - optional .jar library containing the install handler
-   classes.   If specified, the referenced .jar must be contained in the feature
+    classes.   If specified, the referenced .jar must be contained in the
-   archive.   It is specified as a path within the feature archive, relative
+ feature    archive.   It is specified as a path within the feature archive,
-   to the feature.xml   entry. If not specified, the feature archive itself
+ relative    to the feature.xml   entry. If not specified, the feature archive
-  is used to load the install handler classes. This attribute is only interpreted
+ itself   is used to load the install handler classes. This attribute is only
-   if <i>class</i> attribute is also specified</li>
+ interpreted    if <i>class</i> attribute is also specified</li>
             <li> handler - optional identifier of the install handler. The
  value    is  interpreted depending on the value of the <i>library</i> attribute.
-  If        <i>  library</i> is specified,&nbsp; the value is interpreted as
+   If        <i>  library</i> is specified,&nbsp; the value is interpreted
-  a fully qualified  name of a class contained in the specified <i>library</i>.
+ as  a fully qualified  name of a class contained in the specified <i>library</i>.
    If       <i>library</i>   is not specified, the value is is interpreted
  as  an extension identifier  of an extension registered in the <i>org.eclipse.update.installHandlers</i>
-      extension point. In either case, the resulting class must implement the
+       extension point. In either case, the resulting class must implement
-          <i> IInstallHandler</i> interface. The class is dynamically loaded
+ the          <i> IInstallHandler</i> interface. The class is dynamically
-   and called at specific points during feature processing. The handler has
+ loaded   and called at specific points during feature processing. The handler
-  visibility to the API classes from the update plug-in, and Eclipse plug-ins
+ has  visibility to the API classes from the update plug-in, and Eclipse plug-ins
    required by the update plugin.</li>
    </ul>
-Line 628
+Line 641
   text.    Intended to be translated.</li>
    <ul>
-           <li> url - optional URL for the full description as HTML. The URL
+            <li> url - optional URL for the full description as HTML. The
-  can   be  specified as absolute of relative. If relative, it is assumed to
+ URL   can   be  specified as absolute of relative. If relative, it is assumed
-  be relative   to (and packaged in) the feature archive. Note, that for NL
+ to  be relative   to (and packaged in) the feature archive. Note, that for
-  handling the  URL value should be separated to allow alternate URLs to be
+ NL  handling the  URL value should be separated to allow alternate URLs to
-  specified for  each national language. &nbsp;URL support keywords $os$,$ws$,$arch$
+ be  specified for  each national language. &nbsp;URL support keywords $os$,$ws$,$arch$
  and $nl$ that will be replaced by the appropriate operating system, windowing
  system, operating architecture or national language value.</li>
-Line 641
+Line 654
     to  be translated.</li>
    <ul>
-           <li> url - optional URL for the full description as HTML. The URL
+            <li> url - optional URL for the full description as HTML. The
-  can   be  specified as absolute of relative. If relative, it is assumed to
+ URL   can   be  specified as absolute of relative. If relative, it is assumed
-  be relative   to (and packaged in) the feature archive. Note, that for NL
+ to  be relative   to (and packaged in) the feature archive. Note, that for
-  handling the  URL value should be separated to allow alternate URLs to be
+ NL  handling the  URL value should be separated to allow alternate URLs to
-  specified for  each national language. URL support keywords $os$,$ws$,$arch$
+ be  specified for  each national language. URL support keywords $os$,$ws$,$arch$
  and $nl$ that will be replaced by the appropriate operating system, windowing
  system, operating architecture or national language value.</li>
-Line 657
+Line 670
  will be selected for installation   or update using the Eclipse update manager.
   When using nested features, only the nesting parent (ie. the feature selected
   for installation or update) must have click-through license text defined.
-  The license text is required even if the optional <i>url</i> attribute is
+   The license text is required even if the optional <i>url</i> attribute
-  specified.</li>
+ is   specified.</li>
    <ul>
-           <li> url - optional URL for the full description as HTML. The URL
+            <li> url - optional URL for the full description as HTML. The
-  can   be  specified as absolute of relative. If relative, it is assumed to
+ URL   can   be  specified as absolute of relative. If relative, it is assumed
-  be relative   to (and packaged in) the feature archive. Note, that for NL
+ to  be relative   to (and packaged in) the feature archive. Note, that for
-  handling the  URL value should be separated to allow alternate URLs to be
+ NL  handling the  URL value should be separated to allow alternate URLs to
-  specified for  each national language. Note, that the "content" of this URL
+ be  specified for  each national language. Note, that the "content" of this
-  is <b>not</b>    what is presented as the click-through license during installation
+ URL  is <b>not</b>    what is presented as the click-through license during
-  processing.    The click-through license is the actual value of the <i>&lt;license&gt;</i>
+ installation  processing.    The click-through license is the actual value
-      element (eg. <tt>&lt;license&gt;click through text&lt;/license&gt;</tt>).&nbsp;URL
+ of the <i>&lt;license&gt;</i>      element (eg. <tt>&lt;license&gt;click
- support keywords $os$,$ws$,$arch$ and $nl$ that will be replaced by the appropriate
+ through text&lt;/license&gt;</tt>).&nbsp;URL support keywords $os$,$ws$,$arch$
- operating system, windowing system, operating architecture or national language
+ and $nl$ that will be replaced by the appropriate operating system, windowing
- value.</li>
+ system, operating architecture or national language value.</li>
    </ul>
             <li> &lt;url&gt; - optional URL specifying site(s) contain feature
-Line 711
+Line 724
               </li>
               <li>match&nbsp; - optional rule that will be applied when resolving
      the feature reference. A <samp>perfect</samp> match (the default that
- matches    the 2.0.1 behavior) requires that the feature has exactly the
+ matches    the 2.0.1 behavior) requires that the feature has exactly the version
- version specified    by the version attribute. Other choices progressively
+ specified    by the version attribute. Other choices progressively relax
- relax the rule (<samp>    equivalent</samp> allows only service part of the
+ the rule (<samp>    equivalent</samp> allows only service part of the version
- version to be more recent,          <samp>compatible</samp> also allows minor
+ to be more recent,          <samp>compatible</samp> also allows minor part
- part to be included in the   consideration, while <samp>greaterOrEqual</samp>
+ to be included in the   consideration, while <samp>greaterOrEqual</samp>
-  simply allows any version   that is more recent or identical to the one specified).</li>
+   simply allows any version   that is more recent or identical to the one
+ specified).</li>
               <li>search_location&nbsp; - optional. Indicates whether the
- "New   Updates"   action should search the update location determined by
+ "New   Updates"   action should search the update location determined by the
- the nesting   root feature  (<tt>root</tt>, is the default), or the location
+ nesting   root feature  (<tt>root</tt>, is the default), or the location defined
- defined by   the nested feature  (<tt>self</tt>), or search both (<tt>both</tt>)
+ by   the nested feature  (<tt>self</tt>), or search both (<tt>both</tt>)
  in that   order (root first,  self if nothing is found).</li>
    </ul>
-Line 739
+Line 753
  or   plugin must   be specified.</li>
             <li> version - optional plug-in/feature version specification</li>
                 <li>patch - optional specification indicating if this feature
-   is  a  patch of the dependant feature. Default is "false". If patch is
+   is  a  patch of the dependant feature. Default is "false". If patch is true,
- true,   version  must be specified. If patch is true, only feature must be
+   version  must be specified. If patch is true, only feature must be specified.
- specified.   If patch  is true, and match is specified, it must be 'perfect'.<br>
+   If patch  is true, and match is specified, it must be 'perfect'.<br>
                 </li>
             <li> match - optional matching rule. Valid values and processing
   are   as  follows:</li>
-Line 761
+Line 775
  be  at  least  at the version specified, or at a higher service level (major
   and minor version  levels must equal the specified version).</li>
             <li> <b><i>compatible</i></b> - dependent plug-in version must
- be  at  least  at the version specified, or at a higher service level or minor
+  be  at  least  at the version specified, or at a higher service level or
-  level  (major  version level must equal the specified version).</li>
+ minor  level  (major  version level must equal the specified version).</li>
             <li> <b><i>greaterOrEqual</i></b> - dependent plug-in version
  must   be  at least at the version specified, or at a higher service, minor
  or major   level.</li>
        </ul>
      </ul>
-Line 792
+Line 807
  should only    be installed on one of the specified systems. If this attribute
  is not specified,   the feature can be installed on all systems (portable
  implementation).  This   information is used as a hint by the installation
- and update support  (user   can force installation of feature regardless of
+  and update support  (user   can force installation of feature regardless
- this setting).</li>
+ of this setting).</li>
             <li> ws - optional windowing system specification. A comma-separated
     list  of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
      . Indicates this entry should only be installed on one of the specified
-Line 810
+Line 825
  installation   of entry regardless of this setting).</li>
             <li> download-size - optional hint supplied by the feature packager,
     indicating  the download size in KBytes of the referenced plug-in archive.
-    If not specified,  the download size is not known (<b>Implementation Note:</b>
+     If not specified,  the download size is not known (<b>Implementation
-    the implementation  needs to distinguish between "not known" and 0 size)</li>
+ Note:</b>     the implementation  needs to distinguish between "not known"
+ and 0 size)</li>
             <li> install-size - optional hint supplied by the feature packager,
     indicating   the install size in KBytes of the referenced plug-in archive.
     If not specified,   the install size is not known (<b>Implementation Note:</b>
-Line 819
+Line 835
    </ul>
             <li> &lt;data&gt; - identifies non-plugin and non-feature data
- that  is part of the feature. Generally, data are post-install processed using
+  that  is part of the feature. Generally, data are post-install processed
- feature Install handler. Feature files like feature.properties are not considered
+ using feature Install handler. Feature files like feature.properties are
-  data.</li>
+ not considered  data.</li>
    <ul>
            <li> id - required data identifier in the form of a relative path.</li>
-Line 838
+Line 854
  should only    be installed on one of the specified systems. If this attribute
  is not specified,   the feature can be installed on all systems (portable
  implementation).  This   information is used as a hint by the installation
- and update support  (user   can force installation of feature regardless of
+  and update support  (user   can force installation of feature regardless
- this setting).</li>
+ of this setting).</li>
             <li> ws - optional windowing system specification. A comma-separated
     list  of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
      . Indicates this entry should only be installed on one of the specified
-Line 868
+Line 884
  </ul>
            <a name="Feature_Archive_Mapping_Id_To_Path"></a> When interacting
    with   the update site, the feature implementation maps the <tt>&lt;plugin&gt;</tt>
-     and <tt>&lt;data&gt;</tt> elements into path identifiers used by the
+     and <tt>&lt;data&gt;</tt> elements into path identifiers used by the site
- site     to determine the actual files to download and install. The default
+     to determine the actual files to download and install. The default feature
- feature     implementation supplied by Eclipse constructs the path identifiers
+     implementation supplied by Eclipse constructs the path identifiers as
- as follows:
+ follows:
  <ul>
            <li> <tt>&lt;plugin&gt;</tt> element results in a path entry in
  the   form   "<tt>plugins/&lt;pluginId&gt;_&lt;pluginVersion&gt;.jar</tt>"
-Line 887
+Line 903
  <p>Translatable text contained in the feature.xml can be separated into feature&lt;_locale&gt;.properties
      files using Java property bundle conventions. Note that the translated
-  strings   are used at installation time (ie. do not employ the plug-in fragment
+   strings   are used at installation time (ie. do not employ the plug-in
-  runtime   mechanism). </p>
+ fragment   runtime   mechanism). </p>
  <h3> <a name="Plug-In_Archive"></a> Plug-In Archive</h3>
            Plug-ins and plug-in fragments are individually packaged as separate
-Line 899
+Line 915
           <tt>&lt;id&gt;_&lt;version&gt;.jar</tt> </p>
  <p>Where <tt>&lt;id&gt;</tt> is the plug-in or fragment identifier and <tt>
-     &lt;version&gt;</tt> is the full version identifier contained in the respective
+      &lt;version&gt;</tt> is the full version identifier contained in the
-     plugin.xml or fragment.xml. Note that this is a recommended convention
+ respective     plugin.xml or fragment.xml. Note that this is a recommended
-  that   minimizes chance of collisions, but is not required by the Eclipse
+ convention  that   minimizes chance of collisions, but is not required by
-  architecture.   For example, the following are valid plug-in archive names
+ the Eclipse  architecture.   For example, the following are valid plug-in
-  </p>
+ archive names  </p>
  <p><tt>org.eclipse.platform_1.0.3.jar</tt> <br>
           <tt>org.eclipse.ui.nl_2.0.jar</tt> <br>
           <tt>my_plugin.jar</tt> </p>
- <p>Internally, each plug-in archive packages all the relevant plug-in or
+ <p>Internally, each plug-in archive packages all the relevant plug-in or fragment
- fragment files relative to its plug-in or fragment directory (but not including
+ files relative to its plug-in or fragment directory (but not including the
- the directory path element). The archive has the following structure </p>
+ directory path element). The archive has the following structure </p>
  <p><tt>plugin.xml *OR* fragment.xml</tt> <br>
           <tt>other plug-in or feature files and subdirectories</tt> <br>
-Line 920
+Line 936
  </p>
  <h3> <a name="Packaging_NL"></a> Packaging NL</h3>
-           In Eclipse, translated plug-in information is packaged either together
+            In Eclipse, translated plug-in information is packaged either
-     with the base plug-in, or as a plug-in fragment. At runtime, Eclipse
+ together     with the base plug-in, or as a plug-in fragment. At runtime,
- locates     the translations for the required locale. The use of fragments
+ Eclipse locates     the translations for the required locale. The use of
- allows translations     to be added to the runtime without the need to repackage
+ fragments allows translations     to be added to the runtime without the
- the base plug-ins.
+ need to repackage the base plug-ins.
  <p>This mechanism cannot be used for translating the actual packaging information
       that is part of the installation xml files. Consequently the standard
-  Java    translation conventions are used for the packaging information,
+  Java    translation conventions are used for the packaging information, and
- and  all  necessary translations must be available at the time the feature
+  all  necessary translations must be available at the time the feature is
- is packaged.  </p>
+ packaged.  </p>
  <h4> <a name="Translated_Feature_Information"></a> Translated Feature Information</h4>
            <b>Note:</b> This section describes the conventions used for translating
-Line 957
+Line 973
  <p><b>Implementation Note</b>: When accessing the resource bundles the Eclipse
      installation and update code should create a class loader for accessing
-   the  translated string. This way, the standard locale lookup algorithm implemented
+    the  translated string. This way, the standard locale lookup algorithm
-     by Java is automatically used. </p>
+ implemented     by Java is automatically used. </p>
  <p><tt>ResourceBundle b;</tt> <br>
           <tt>ClassLoader l;</tt> <br>
-Line 994
+Line 1010
  <h3> <a name="Custom_Install_Handling"></a> Custom Install Handling</h3>
            Custom install handlers are written as a Java class and are packaged
     as  part of the <a href="#Feature_Archive">feature archive</a> . The installer
-     must implement the <tt>IInstallHandler</tt> interface (in most cases
+     must implement the <tt>IInstallHandler</tt> interface (in most cases will
- will     extend the <tt>BaseInstallHandler</tt> abstract helper class which
+     extend the <tt>BaseInstallHandler</tt> abstract helper class which implements
- implements     <tt>IInstallHandler</tt>). When required, the install handler
+     <tt>IInstallHandler</tt>). When required, the install handler is dynamically
- is dynamically     loaded by the installation and update code, and is called
+     loaded by the installation and update code, and is called at specific
- at specific points    during its processing. The install handler code has
+ points    during its processing. The install handler code has visibility
- visibility to classes    from the installation and update support plug-in,
+ to classes    from the installation and update support plug-in, and its prerequisite
- and its prerequisite  plug-ins.
+  plug-ins.
- <p><b>Implementation Note:</b> the detailed list of visible prerequisite
+ <p><b>Implementation Note:</b> the detailed list of visible prerequisite plug-ins
- plug-ins is still evolving. It is expected to include <tt>org.eclipse.core.boot
+ is still evolving. It is expected to include <tt>org.eclipse.core.boot </tt>
- </tt> and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</tt>
+ and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</tt>
-      and <tt>org.eclipse.swt</tt> when running with full workbench (ie. not
+       and <tt>org.eclipse.swt</tt> when running with full workbench (ie.
-   "headless  mode"). Also, it would be useful to always expose <tt>org.eclipse.core.ant</tt>
+ not    "headless  mode"). Also, it would be useful to always expose <tt>org.eclipse.core.ant</tt>
       so that build scripts can be used as part of the install handler implementation.
       </p>
-Line 1040
+Line 1056
  a  feature    is selected for removal, but before any of the standard uninstall
   processing    has taken place. It is passed the custom install log created
   by the install    handler install-completion step.</li>
-            <li> uninstall-completion - the install handler is called on completion
+             <li> uninstall-completion - the install handler is called on
-     of the standard uninstall steps. It is passed the custom install log created
+ completion      of the standard uninstall steps. It is passed the custom
-     by the install handler install-completion step.</li>
+ install log created     by the install handler install-completion step.</li>
  </ul>
            Note, that as a general practice, install handlers should be provided
-Line 1073
+Line 1089
  </ul>
            In general, when processing signed jars, the user will be prompted
-   for   each unrecognized certificate. The response choices will include
+   for   each unrecognized certificate. The response choices will include aborting
- aborting     the installation (originator is not trusted), continuing the
+     the installation (originator is not trusted), continuing the installation
- installation     (originator is trusted for this installation).
+     (originator is trusted for this installation).
  <h2> <a name="Update_Server"></a> Update Server</h2>
            The default Eclipse update server is any URL-accessible server.
  The   default   implementation assumes a fixed-layout server. The content
-Line 1084
+Line 1100
  or can be  dynamically   computed by the server.
  <h3> <a name="Site_Map"></a> Site Map</h3>
            The update server URL can be specified as a full URL to the site
-  map   file,   or a URL of a directory path containing the site map file
+  map   file,   or a URL of a directory path containing the site map file (similar
- (similar    to index.html   processing). The site map site.xml format is
+    to index.html   processing). The site map site.xml format is defined by
- defined by  the  following dtd:
+  the  following dtd:
  <p><tt>&lt;?xml encoding="ISO-8859-1"?&gt;</tt> </p>
  <p><tt>&lt;!ELEMENT site (description?, feature*, archive*, category-def*)&gt;</tt>
-Line 1166
+Line 1182
  not    specified, the default is the URL location of the site.xml file.</li>
    </ul>
-            <li> &lt;description&gt; - brief description as simple text. Intended
+             <li> &lt;description&gt; - brief description as simple text.
-     to be translated.</li>
+ Intended     to be translated.</li>
    <ul>
-           <li> url - optional URL for the full description as HTML. The URL
+            <li> url - optional URL for the full description as HTML. The
-  can   be  specified as absolute of relative. If relative, If relative, is
+ URL   can   be  specified as absolute of relative. If relative, If relative,
-  relative   to site.xml.</li>
+ is   relative   to site.xml.</li>
             <br>
           Note, that for NL handling the URL value should be separated to
  allow    alternate  URLs to be specified for each national language.
-Line 1197
+Line 1213
  match  the  version specified in the feature.xml of the referenced archive
  (the url attribute).  If specified, the id attribute must also be specified.</li>
             <li> url - required URL reference to the feature archive. Can
- be  relative    or absolute. If relative, it is relative to the location
+ be  relative    or absolute. If relative, it is relative to the location of
- of the  site.xml   file.       <b>Note</b>: the default site implementation
+ the  site.xml   file.       <b>Note</b>: the default site implementation
- allows  features  to be accessed without being explicitly declared using a
+  allows  features  to be accessed without being explicitly declared using
- &lt;feature&gt;  entry. By default, an undeclared features reference is interpreted
+ a &lt;feature&gt;  entry. By default, an undeclared features reference is
- as "features/&lt;id&gt;_&lt;version&gt;.jar"</li>
+ interpreted as "features/&lt;id&gt;_&lt;version&gt;.jar"</li>
              <li>label - optional feature label. The value is used for optimization
      when browsing the site from the update manager. Intended to be translated.<br>
             </li>
-Line 1209
+Line 1225
     list  of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
      . Indicates this feature should only be installed on one of the specified
       os systems. If this attribute is "*", the feature can be installed
-  on   all systems (portable implementation). This information is used as
+ on   all systems (portable implementation). This information is used as a
- a hint   by the installation and update support (user can force installation
+ hint   by the installation and update support (user can force installation
  of feature   regardless of this setting).</li>
             <li> arch - optional machine architecture specification. A comma-separated
      list of architecture designators defined by Eclipse (see Javadoc for
-Line 1227
+Line 1243
   a  hint by the installation and update support (user can force installation
    of feature regardless of this setting).</li>
             <li> nl - optional locale specification. A comma-separated list
-  of  locale   designators defined by Java. Indicates this feature should
+  of  locale   designators defined by Java. Indicates this feature should only
- only  be installed   on a system running with a compatible locale (using
+  be installed   on a system running with a compatible locale (using Java
- Java locale-matching    rules). If this attribute&nbsp;is "*", the feature
+ locale-matching    rules). If this attribute&nbsp;is "*", the feature can
- can be installed on all  systems (language-neutral implementation). This
+ be installed on all  systems (language-neutral implementation). This information
- information is used as a hint by the installation and update support (user
+ is used as a hint by the installation and update support (user can force
- can force installation  of feature regardless of this setting).</li>
+ installation  of feature regardless of this setting).</li>
             <li>patch - optional specification indicating if this feature
  is  a   patch. Default is "false".&nbsp;</li>
    </ul>
             <li> &lt;archive&gt; - identifies referenced "storage" archive
  (the   actual  files referenced via the <tt>&lt;plugin&gt;</tt> or <tt>&lt;data&gt;</tt>
-      elements in the feature manifest). The site simply manages archives as
+       elements in the feature manifest). The site simply manages archives
-   a  path-to-URL map. The default Eclipse site implementation does not require
+ as   a  path-to-URL map. The default Eclipse site implementation does not
-     the &lt;archive&gt; section to be included in the site map (site.xml).
+ require     the &lt;archive&gt; section to be included in the site map (site.xml).
   Any   archive reference not explicitly defined as part of an &lt;archive&gt;
   section   is assumed to be mapped to a url in the form "&lt;archivePath&gt;"
   relative   to the location of the site.xml file.</li>
-Line 1249
+Line 1265
    <ul>
            <li> path - required archive path identifier. This is a string
  that   is  determined  by the <a
-  href="#Feature_Archive_Mapping_Id_To_Path">feature</a>      referencing
+  href="#Feature_Archive_Mapping_Id_To_Path">feature</a>      referencing this
- this archive and is not otherwise interpreted by the site  (other   than
+ archive and is not otherwise interpreted by the site  (other   than as a
- as a lookup token).</li>
+ lookup token).</li>
             <li> url - required URL reference to the archive. Can be relative
    or  absolute.  If relative, it is relative to the location of the site.xml
    file.</li>
    </ul>
             <li> &lt;category-def&gt; - an optional definition of a category
-  that   can be used by installation and update support to hierarchicaly organize
+   that   can be used by installation and update support to hierarchicaly
-    features</li>
+ organize    features</li>
    <ul>
            <li> name - category name. Is specified as a path of name tokens
-Line 1306
+Line 1322
 ways: </p>
  <ul>
-           <li> by supplying server-side logic on the update server (eg. implementing
+            <li> by supplying server-side logic on the update server (eg.
-     servlets that compute the site.xml map, and control access to individual
+ implementing      servlets that compute the site.xml map, and control access
-    archives based on some user criteria)</li>
+ to individual     archives based on some user criteria)</li>
             <li> by supplying a custom concrete implementation of the site
  object    (installed  on the client machine, update server specified <tt>&lt;site
-   type=""&gt;</tt>  ). The custom concrete site implementation, together
+   type=""&gt;</tt>  ). The custom concrete site implementation, together with
- with   any server-side   logic support the required control mechanisms.</li>
+   any server-side   logic support the required control mechanisms.</li>
  </ul>
            Eclipse provides an example demonstrating an implementation of
-Line 1343
+Line 1359
           <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
     META_INF/</tt>   </p>
- <p><b>Implementation Note:</b> we will go back to the original design of
+ <p><b>Implementation Note:</b> we will go back to the original design of not
- not splitting out fragments (ie. plugin and fragments go into the same install
+ splitting out fragments (ie. plugin and fragments go into the same install
      location) </p>
  <h3> <a name="Unmanaged_Plugins"></a> "Unmanaged" Plug-Ins</h3>
-           Eclipse supports a concept of "unmanaged" plug-ins. These are plug-ins
+            Eclipse supports a concept of "unmanaged" plug-ins. These are
-     that were directly installed into the Eclipse file tree without being
+ plug-ins     that were directly installed into the Eclipse file tree without
- part    of a feature (eg. developer unzipping plug-in archive directly into
+ being part    of a feature (eg. developer unzipping plug-in archive directly
- the  Eclipse  file tree).
+ into the  Eclipse  file tree).
- <p>Eclipse runtime recognizes these plugins during startup and loads the
+ <p>Eclipse runtime recognizes these plugins during startup and loads the plug-in
- plug-in information into the runtime registry following the standard plug-in
+ information into the runtime registry following the standard plug-in binding
- binding rules. The update support also recognizes the presence of this new
+ rules. The update support also recognizes the presence of this new plug-in,
- plug-in, but since this plug-in is not part of any feature it cannot be updated
+ but since this plug-in is not part of any feature it cannot be updated using
- using the update support (hence "unmanaged"). Unmanaged plug-in that become
+ the update support (hence "unmanaged"). Unmanaged plug-in that become referenced
- referenced by a feature as a result of some future installation or update
+ by a feature as a result of some future installation or update action become
- action become "managed" (can be updated as part of the feature). </p>
+ "managed" (can be updated as part of the feature). </p>
  <p>Unmanaged plug-ins are not displayed as part of the installation and update
      UI. </p>
-Line 1372
+Line 1388
  <p>However, when using native platform installers, performing native uninstall
       creates problems because plug-ins would be removed without regard to
- any    sharing relationships. As a result, Eclipse <b>does not allow</b>
+ any    sharing relationships. As a result, Eclipse <b>does not allow</b> plug-ins
- plug-ins    to be installed using native installers into the shared installation
+    to be installed using native installers into the shared installation tree.
- tree.    Instead, native installers must establish their own installation
+    Instead, native installers must establish their own installation root
- root directory.    The subdirectory structure is the same as defined for
+ directory.    The subdirectory structure is the same as defined for base
- base Eclipse. The  private  root directory is logically linked into the shared
+ Eclipse. The  private  root directory is logically linked into the shared
   Eclipse installation   via  a link file installed by the native installer.
   The file path for the   link  file is <tt>&lt;configRoot&gt;/links/</tt>.
   The <tt>&lt;configRoot&gt;   </tt>  location is computed by Eclipse relative
-Line 1401
+Line 1417
   Default is to  allow updates&nbsp; (w). </p>
  <p>Eclipse does not manage the linked directories in any way. It simply detects
-     their existence by the presence of the link files, and includes the linked
+      their existence by the presence of the link files, and includes the
-     plug-ins during the platform startup. The native installer is responsible
+ linked      plug-ins during the platform startup. The native installer is
-     for uninstalling the link when the corresponding directory is removed.
+ responsible      for uninstalling the link when the corresponding directory
-  Eclipse   runtime ignores any links that cannot be resolved. <br>
+ is removed.   Eclipse   runtime ignores any links that cannot be resolved.
+ <br>
           &nbsp; </p>
           <br>
          <br>
-Line 1412
+Line 1429
        <br>
       <br>
      <br>
+        <br>
  </body>
  </html>

 Legend:



Removed from v.1.14
 


changed lines


 
Added in v.1.15
 Legend:



Removed from v.1.14
 


changed lines


 
Added in v.1.15
-Removed from v.1.14
+Added in v.1.15

help@eclipse.org	ViewVC Help
Powered by ViewVC 1.0.3