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 "Pack200" and "Adaptor Hooks"

(Difference between pages)
 
 
Line 1: Line 1:
−
==Overview==
+
== Overview ==
−
<p>Pack200 is a compression technology included in Java 1.5.0.  It was designed for compressing jars and works most efficiently on Java class files.  Using Pack200 compression can reduce the size of a jar by about 60%.  By packing the jars placed on an update site and enabling update to unpack those jars after download, the amount of data downloaded during an update can be greatly reduced.</p>
+
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.
−
<br>
+
−
===Signing===
+
−
<p>Pack200 is not a lossless compression.  Packing and unpacking will produce a jar that is semantically the same as the original, but classfile structures will be rearranged; the resulting jar will not be identical to the original.  However, this reordering is idempotent so a second pack-unpack will not further change the jar.</p>
+
−
<p>Signing a jar hashes the contents and stores the hash codes in the manifest.  Since packing and unpacking a jar will modify the contents, the jar must be normalized prior to signing.  Normalizing the jar will also be refered to as repacking the jar.</p>
+
  
−
== Jar Processor ==
+
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.
−
<p>The Jar Processor is a tool provided by the org.eclipse.update.core bundle that will recursively run the pack200, signing, and unpack200 tools on a jar and its nested jars.  The jar processor can be used during a build to repack, sign and pack jars for an update site. It is also used by eclipse itself to unpack compressed jars downloaded from an update site.</p>
+
  
−
<p>To use the jar processor in a The jar processor can be exported into a self contained jar using the <code>org.eclipse.update.internal.jarprocessor/jarprocessor.jardesc</code> jar description file.  The jar processor can also be accessed through the <code>org.eclipse.update.core.siteOptimizer</code> application.  The jar processor requires a 1.5 jre to perform the pack and unpack.</p>
+
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.
−
<pre>java -jar /eclipse/startup.jar -application org.eclipse.update.core.siteOptimizer -jarProcessor [options] [input] </pre>
+
−
The jarprocessor understands the following command-line options:
+
−
{| border="1" cellpadding="2"
+
−
!width="150"|Option
+
−
!width="500"|Effect
+
−
|-
+
−
|&ndash;repack
+
−
|Normalize the jar by calling the pack200 tool with the -repack option.
+
−
|-
+
−
|&ndash;pack
+
−
|Pack the jar using the pack200 tool
+
−
|-
+
−
|&ndash;sign <command>
+
−
|Sign the jar using the provided command.  The sign command will be provided the name of the jar to sign as its first argument.
+
−
|-
+
−
|&ndash;unpack
+
−
|Unpack a pack.gz file into a jar using the unpack200 tool.
+
−
|-
+
−
|&ndash;outputDir <directory>
+
−
|The directory in which to place the results.
+
−
|-
+
−
|&ndash;verbose
+
−
|Use verbose mode
+
−
|}
+
−
<p>The repack, sign and pack options can be specified together.  When specifying all 3, the input jar will first be normalized, then signed, then packed.  The output will be the signed jar and a packed jar.pack.gz file.</p>
+
−
<br>
+
−
===Input===
+
−
<p>The jar processor takes as input either a .zip file, a .jar (or .pack.gz) file, or a directory.
+
−
*If the input is a zip file, then each contained .jar (or .pack.gz if unpacking) will be processed.  A new .zip file will be created in the output directory containing the results. 
+
−
*If the input is a single .jar (or .pack.gz file) then that file is processed.
+
−
*If the input is a directory then all .jar (or .pack.gz files) in that directory, and its subdirectories, will be processed.
+
−
</p><br>
+
−
<p>If the input is a zip file, then additional options may be specified by placing a <code>pack.properties</code> file in the root of the zip.  This file is a java properties file and the following properties are supported:
+
−
*pack.excludes : A comma-delimited list of JARs that should not be packed or repacked.
+
−
*sign.excludes : A comma-delimited list of JARs that should not be signed.
+
−
*<jarname>.pack.args : A comma-delimited list of additional arguments that should be passed to pack200 when packing any jar with name <jarname>.
+
−
</p>
+
−
<br>
+
−
===Examples===
+
−
<pre>
+
−
java -jar /eclipse/startup.jar -application org.eclipse.update.core.siteOptimizer -jarProcessor
+
−
-repack -sign signing-script.sh -outputDir ./out eclipse-SDK.zip
+
−
</pre>
+
−
<p>This will run the jar processor using the siteOptimizer application.  For each jar file in eclipse-SDK.zip, the jar processor will normalize the jar by repacking it, then sign it by executing <code>signing-script.sh <jar></code>.  A zip ./out/eclipse-SDK.zip will be created containing the repacked signed jars.  Any non-jar file in the input eclipse-SDK.zip will be copied over to the ./out/eclipse-SDK.zip as is.</p>
+
−
<pre>
+
−
java -jar /eclipse/startup.jar -application org.eclipse.update.core.siteOptimizer -jarProcessor
+
−
-repack -sign signing-script.sh -pack -outputDir ./out eclipse-SDK.zip
+
−
</pre>
+
−
<p>This command will do the same as the first example, but will also pack the signed jars.  The output ./out/eclipse-SDK.zip file will contain both the signed jars and the .jar.pack.gz versions.</p>
+
−
<pre>
+
−
java -jar /eclipse/startup.jar -application org.eclipse.update.core.siteOptimizer -jarProcessor
+
−
-pack myJar.jar
+
  
−
java -jar /eclipse/startup.jar -application org.eclipse.update.core.siteOptimizer -jarProcessor
+
== Hookable Adaptor ==
−
  -unpack myJar.jar.pack.gz
+
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.
−
</pre>
+
 
−
<p>These two commands are the inverses of each other.  The first will pack <code>myJar.jar</code> and produce a <code>myJar.jar.pack.gz</code>.  Since no outputDir is specified, the .pack.gz file will be created in the current directory.  If <code>myJar.jar</code> contained a nested jar, then that nested jar will be packed first and the resulting <code>myJar.jar.pack.gz</code> would contain a nested <code>nested.jar.pack.gz</code>.  The second command will unpack the <code>myJar.jar.pack.gz</code> file and produce a <code>myJar.jar</code>.  The nested <code>nested.jar.pack.gz</code> will also be unpacked.  Again, because no outputDir is specified, the output will be in the current directory, overwriting the original <code>myJar.jar</code>.</p>
+
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).   
−
<br>
+
 
−
===Pack200 Executable location===
+
=== The Base Adaptor ===
−
<p>By default, the jar processor will look for the pack200 and unpack200 executables first in the <code>${java.home}/bin</code> directory and then on the system search path.  However, the location of these tools can also be specified using the java system property <code>org.eclipse.update.jarprocessor.pack200</code>. The value is expected to be the directory containing the pack200 and unpack200 executables or one of the following special values:
+
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.
−
*"@jre" - find unpack200 in ${java.home}/bin
+
 
−
*"@path" - find unpack200 on the search path
+
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.
−
*"@none" - pack200 not supported, download normal jars from update sites.
+
 
−
</p>
+
=== The Hook Registry ===
−
<br>
+
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.
−
== Related Pages ==
+
 
−
*[[Update Site Optimization]]
+
==== Hook Configurators ====
−
*[[Callisto Coordinated Update Sites]]
+
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.
−
*[[JAR Signing]]
+
 
−
===External Links===
+
==== Discovering Hook Configurators ====
−
[http://java.sun.com/j2se/1.5.0/docs/guide/deployment/deployment-guide/pack200.html Pack200 and Compression]<br>
+
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).
−
[http://java.sun.com/j2se/1.5.0/docs/tooldocs/share/pack200.html JAR Packing tool]<br>
+
 
−
[http://java.sun.com/j2se/1.5.0/docs/tooldocs/share/unpack200.html JAR Unpacking tool]<br>
+
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.
−
[http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/jarsigner.html JAR Signing and Verification tool]<br>
+
 
 +
===== 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:
 +
 
 +
<code>
 +
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
 +
</code>
 +
 
 +
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 ==

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

Retrieved from "https://wiki.eclipse.org/index.php?title=Pack200&oldid=4220"

Back to the top