## What's New in 4.1

Here are descriptions of some of the changes of interest to plug-in developers made to the Eclipse Platform, Equinox and SWT for the 4.1 release of Eclipse. All changes between Eclipse platform 4.0 and 4.1 are included here, which includes changes that were also made in the 3.7 release.

There are also many new features oriented towards end-users of the platform that can be viewed in the What's new section of the Workbench User Guide.

## Platform Changes

Builder framework enhancements

The platform now supports multiple build configurations per project. Build configurations allow a project to be built in different ways. The build commands can discover which configuration is currently being built. Builder resource deltas are stored per configuration.

New API has been introduced to define references between the configurations and to build chosen configurations and their references. See `org.eclipse.core.resources.IBuildConfiguration` for further details.

Builders also now have access to a build context that can be used to discover the source of the build request, as well as the build configurations being built during the current build invocation. See `org.eclipse.core.resources.IncrementalProjectBuilder#getContext` for further details.

Help search refinement | The new extension point `org.eclipse.help.base.searchProcessor` allows for modification of the search term, suggestion of alternate terms and modification of the list of search results.
Extension point for changing help main page | A new extension point, `org.eclipse.help.base.display`, allows for an alternate web page instead of help/index.jsp to be opened when Help > Contents is invoked from the workbench menu.
Remote help styling | The new preference `org.eclipse.help.base/remote_css` allows the definition of a style sheet which is included in all help pages that originated from a remote infocenter.

Variables in launch shortcuts

Previously when you contributed a launch shortcut, the only variable you had available for examination was the current selection in the workspace. Now you have all of the variables from the Platform evaluation context available as well.

For example you can now ask if your bundle has been loaded yet to prevent your launch shortcut from appearing when it should not.

          <enablement>
            <with variable="selection">
              <count value="1"/>
                 <iterate>
                    <and>
                        <test property="org.eclipse.my.bundle.tester" value="true"/>
                        <with variable="org.eclipse.core.runtime.Platform">
                           <test
                                 args="org.eclipse.my.bundle"
                                 property="org.eclipse.core.runtime.bundleState"
                                 value="ACTIVE">

                           </test>
                        </with>
                    </and>
                 </iterate>
            </with>
          </enablement>

ProjectSetCapability API extension | The ProjectSetCapability API now supports SCM URLs (see http://maven.apache.org/scm/scm-url-format.html). An URL in that format is now accepted by ProjectSetCapability#asReference(URI, String) method. Currently, only CVS provides an extended implementation of the method.

Eclipse Test Framework writes stackdumps on timeout

The Eclipse Test Framework (org.eclipse.test) now writes stackdumps to `System.err` shortly before a test gets killed by the `<java fork="true" timeout="${timeout}" ...>` Ant task.

Where before, you just saw:

         [java] Timeout: killed the sub-process
         [java] Java Result: -1

You now get the process memory stats, followed by a stackdump of all threads, followed by the current focus control (with all its parents), and the open shells, e.g.:

         [java] EclipseTestRunner almost reached timeout '7200000'.
         [java] totalMemory: 260177920
         [java] freeMemory (before GC): 195046224
         [java] freeMemory (after GC):  244342384
         [java] Thread dump at 2011-04-21 06:41:49 -0400:
         [java] java.lang.Exception: Worker-JM
         [java] 	at java.lang.Object.wait
         [java] 	at org.eclipse.core.internal.jobs.InternalWorker.run
         [java] ...
         [java] java.lang.Exception: main
         [java] 	at org.eclipse.swt.internal.win32.OS.WaitMessage
         [java] 	at org.eclipse.swt.widgets.Display.sleep
         [java] 	at pack.TestClass.testMethod
         [java] ...
         [java] FocusControl:
         [java] Tree {}
         [java] Shell {}
         [java] Shells:
         [java] visible: Shell {Java - Eclipse SDK}
         [java] visible: Shell {}

The whole dump is repeated 5 seconds later. Since the code that prints the SWT information uses `display.syncExec(..)`, this may or may not influence a hung main thread.

## Equinox Changes

OSGi R4.3 Core Framework API update

The upcoming OSGi R4.3 Core Specification includes many updates to core framework API. This includes introducing generics in the framework and other core API.

The framework package is updated in several ways. First, generic types are added to existing API where appropriate. Second, new API is added to exploit generic type safety. In particular there is new API in the service registry to facilitate working with type parameters. Finally, in order to tidy up the overall framework API, an adapt method was added to the `Bundle` interface to allow it to be adapted to types in the new `org.osgi.framework.wiring` and `org.osgi.framework.startlevel` packages. These new packages replace the `org.osgi.service.packageadmin` and `org.osgi.service.startlevel` packages, respectively, both of which are now deprecated.

The tracker API is also updated to use generic types. A new constructor is added to `ServiceTracker` which take a class argument for type safety. New `getTracked` methods are added to both `BundleTracker` and `ServiceTracker` to return a map for keys to values.

OSGi has a requirement to support J2ME foundation 1.1, even with the introduction of generic API. For J2ME platforms, the OSGi API is compiled in a way that allows it to continue running on J2SE 1.4 based VMs (a compiler option known as jsr14). The Equinox core framework uses this option when it is built and we still support J2SE 1.4 and J2ME Foundation 1.1 runtime environments.

For more information see the upcoming OSGi Service Platform Release 4 Core and Compendium Version 4.3 Early Draft 3 available December 20th, 2010.

Framework Hooks

The upcoming OSGi R4.3 Core Framework Specification includes new framework hooks that provide a means for a bundle to hook into the resolver, bundle events and accessing bundles via the bundle context. These hooks build upon the concepts already available in the service hooks introduced in the OSGi R4.2 Core Specification (package org.osgi.framework.hooks.service).

The framework hook specification provides a number of new mechanisms that closely interact with the built-in resolver and lifecycle layer of the framework. These interactions are not intended for use by application bundles. Modifying the behavior of the module and lifecycle layer requires developers to closely follow the semantics of the OSGi module and lifecycle model and this is often hard, requiring a significant amount of code. The resolver hook API is included in the `org.osgi.framework.hooks.resolver` package. The bundle event and find hooks are included in the `org.osgi.framework.hooks.bundle` package.

OSGi middleware developers may notice that the composite bundle specification and concept will not be included in the upcoming OSGi R4.3 Core Specification. The OSGi Core Expert Group decided against building the concept of composite bundles directly into the framework. Instead these new core framework hooks have been introduced to allow a layer on top to provide isolation in a similar fashion as the composite bundle concept from earlier OSGi draft specification proposals.

For more information see the upcoming OSGi Service Platform Release 4 Core and Compendium Version 4.3 Early Draft 3 available December 20th 2010.

Weaving Hooks

The upcoming OSGi R4.3 Core Framework Specification includes new hooks for manipulating class bytecode at runtime (or bytecode weaving). Bytecode weaving has become more popular, in particular due to its inclusion in the core Java API, and so there are a number of bytecode weaving technologies that would benefit from weaving support in the OSGi runtime. Bytecode weaving requires tight integration with the class loader for the class to be woven, and also can alter the class dependency graph.

To support bytecode weaving a new weaving hook is defined in the package `org.osgi.framework.hooks.weaving`. The weaving hook allows a hook implementation to manipulate the bytecode of a class before it is defined by an OSGi class loader. In cases where the class dependency graph has changed, a weaving hook is able to add additional package constraints to the bundle that is being woven.

For more information see the upcoming OSGi Service Platform Release 4 Core and Compendium Version 4.3 Early Draft 3 available December 20th 2010.

Generic Capabilities

The upcoming OSGi R4.3 Core Framework Specification includes a new generic dependency model for bundles that will be understood and enforced by the framework resolver. Since existing resolve-time dependencies (Import-Package, Require-Bundle etc.) are related to code visibility management, the resolution of such dependencies has traditionally indicated that the bundles in question are ready to share and/or use their code. With the introduction of a generic dependency model, a bundle can provide and require capabilities that are not related to code.

New OSGi bundle manifest headers are introduced to declare arbitrary provided capabilities (`Provide-Capability`) and requirements on them (`Require-Capability`). These headers impact the resolution of the bundles involved and the dependencies among them, but have no other impact. It is predicated solely on the existence of declared capabilities to satisfy declared requirements and nothing more.

Those familiar with Equinox may notice a similarity between the generic dependency model in OSGi R4.3 and the Equinox specific manifest headers `Eclipse-GenericCapability` and `Eclipse-GenericRequire`. The OSGi R4.3 generic dependency model provides an equivalent and standard way for defining generic capabilities and requirements. Developers are encouraged to migrate off the Equinox specific headers to the new OSGi headers for generic capabilities and requirements.

For more information see the upcoming OSGi Service Platform Release 4 Core and Compendium Version 4.3 Early Draft 3 available December 20th 2010.

Unified logging

Eclipse and Equinox currently have several logging APIs which do not always work together nicely. This includes `ILog`, `FrameworkLog`, and the OSGi `LogService`, among others. For the 3.7 release Equinox has pulled the Extended OSGi log service into the core framework to aggregate and unify the various logging APIs within the Eclipse Platform. Before this unification it was not possible for an `ILogListener` to listen to entries logged directly to the `FrameworkLog` or to the OSGi `LogService`. Similarly, it was not possible for an OSGi `LogListener` to listen to entries logged directly to the `FrameworkLog` or an `ILog`. Now through the use of the `ExtendedLogService`, included in the core framework, listeners can listen to logs coming from any source as long as they are aggregated through the extended log service.

The package `org.osgi.service.log` contains the OSGi LogService API and `org.eclipse.equinox.log` contains the Equinox extended OSGi log service API. Both packages are exported by the core framework (`org.eclipse.osgi`). All eclipse logging APIs are now aggregated through the `org.eclipse.equinox.log.Logger` with the name `org.eclipse.equinox.logger`. All `ILogListener` instances will be notified of entries logged through this logger. OSGi `LogListener` instances will also be notified of entries logged through this logger as well as entries logged through any other logger. The `ExtendedLogReaderService` in Equinox also allows OSGi `LogListener` instances to listen to specific loggers through the use of a filter.

Reduced memory use when loading p2 repositories

Several changes were made to reduce memory usage during and after loading p2 repositories. Although actual savings depends on the composition of the repositories being loaded we are seeing an average reduction of 23% in the peak memory usage and heap expansion during the load and an average reduction of 19% in memory used to store the repository after the load. Using a sample Eclipse build repository with 10 integration builds, this translates to a reduction in peak memory usage from 92 MB to 71 MB, and a reduction in retained memory after the load of 48 MB to 39 MB.

To maintain repository compatibility between different versions of Eclipse, most of these savings will only be realized when reading repositories generated with a 3.7 or later Eclipse.

More metadata customizations in p2

Applications can now set the `-vm` command-line argument within p2 metadata by using the `setJvm` touchpoint instruction.

    <touchpointData ...>
       <instructions ...>
          <instruction key='configure'>
             setJvm(jvm:/usr/bin/java);
          </instruction>
          ...
    </touchpointData>

You can also incrementally add program property arguments. This is useful particularly for the case where you have a property in the `config.ini` file whose value is a comma-separated list. Calling `addProgramProperty` will add the value to the end of the list and calling `removeProgramProperty` will remove it from the list. If it is the only item in the list and it is removed, then the property itself is removed.

    <touchpointData ...>
       <instructions ...>
          <instruction key='configure'>
             addProgramProperty(propName:myKey,propValue:myValue);
          </instruction>
          <instruction key='unconfigure'>
             removeProgramProperty(propName:myKey,propValue:myValue);
          </instruction>
          ...
    </touchpointData>

Add labels to install history states

When using the p2 director application to install from the command-line, you can now tag the operation with a label that you can later refer to. This label will appear next to the associated entry in the Installation History table and you can later refer to it when using the director application to revert to a particular installation state.

You call the director application with the `-tag <tagName>` argument to set the tag.

    d:\builder\eclipse.exe
       -application org.eclipse.equinox.p2.director
       -repository http://download.eclipse.org/releases/helios/
       -installIU org.eclipse.cdt.feature.group
       -tag AddCDT
       -destination d:/eclipse/
       -profile SDKProfile

To get a list of tags for a particular profile, invoke the application with the `-listTags` argument.

    d:\builder\eclipse.exe
       -application org.eclipse.equinox.p2.director
       -listTags
       -profile SDKProfile

The list of tags is also available from the About Eclipse -> Installation Details -> Installation History view.

Use the p2 director to download only

You can now use the p2 director application to download artifacts without installing them. This is done by invoking the application with the `-downloadOnly` flag.

    d:\builder\eclipse.exe
       -application org.eclipse.equinox.p2.director
       -repository http://download.eclipse.org/releases/helios/
       -installIU org.eclipse.cdt.feature.group
       -downloadOnly
       -destination d:/eclipse/
       -profile SDKProfile

## SWT Changes

Touch and gesture support

If your hardware supports it, you can now listen for touches or gestures on SWT controls. Four standard gestures are supported: two-finger panning, rotation, magnification, and swipe (three fingers on Mac OS X, flicks on Windows). You can also listen for 'raw' touches on a MacBook touchpad, Magic Trackpad or Magic Mouse, or a touch-sensitive display that is supported by Windows Touch. For examples of how to use the touch and gesture support see Snippet 352 and Snippet 353.

WebKit everywhere | The SWT browser now supports using WebKit as its native renderer on Windows. Consequently, browsers created with new style `SWT.WEBKIT` will use WebKit on Windows, Linux and OS X, provided that the user's machine satisfies the runtime requirements. For an example of using WebKit see Snippet 351.
Browser on Linux defaults to WebKitGTK+ | Browsers created with style `SWT.NONE` on Linux now use WebKitGTK+ as the default native renderer if it is found on the user's machine. If WebKitGTK+ is not found then a Mozilla-based native renderer is used instead.
Change orientation | New API `setOrientation()` has been added to `Control` and `Menu` to allow the application to change the orientation on instances of these widgets. Prior to the introduction of `setOrientation()` the application had to recreate the widgets in order to do this. Note that these methods are only relevant on platforms where BIDI mirroring is supported.
Accessible editable text support | SWT Accessibility now has API to support the platform's EditableText interface used by accessibility tools such as speech recognition systems. Clients can add support for this to their custom controls by providing an implementation of new interface AccessibleEditableTextListener.
Duplex printing | New API has been added to `PrinterData` to enable duplex (double-sided) printing without using the `PrintDialog`. This can also be used to seed the `PrintDialog`'s duplex setting before presenting it to the user.
Tool shell support on Cocoa | The Cocoa port now supports the `SWT.TOOL` style bit. For an example of this see Snippet 344.
Wrappable buttons | The button control now supports the SWT.WRAP style bit on all platforms. This allows for the creation of buttons that will automatically wrap any text when resized. For an example of this see Snippet 345.
Cocoa getMenuBar | `Display.getMenuBar()` is a new API that returns a menu that is displayed when no shell is visible or when the active shell doesn't have a menu bar of its own. This API is currently only available in the Mac OS X Cocoa port; it returns `null` on all other platforms. See Snippet 347 for an example of using this API in a cross-platform application.

Cocoa getSystemMenu

`Display.getSystemMenu()` is a new API that returns the system-provided menu for the application. You can access menu items in the system menu by comparing a `MenuItem`'s id with various `SWT.ID_`* constants. This API is currently only available in the Mac OS X Cocoa port; it returns `null` on all other platforms. See Snippet 354 for an example of using this API in a cross-platform application.

Cocoa getToolBar

`Shell.getToolBar()` returns a tool bar that appears in the title area of the shell. Tool items added to that tool bar will have the look and feel of the platform. You can also add special separator items that provide a fixed-width spacer or a flexible-width spacer that pushes the tool items on either side of it out to the next fixed item, or the edge of the shell. This API is currently only available in the Mac OS X Cocoa port; it returns `null` on all other platforms.

Text setTextChars | There is new API in Text that allows applications to get and set text as a char array in a secure manner. For an example of this see Snippet 346.
Improved Cocoa DateTime support | On Cocoa the `DateTime` control now supports the `SWT.DROP_DOWN` style bit.
Improved GTK DateTime support | On GTK, the `DateTime` control now supports `SWT.DROP_DOWN` style to drop down a calendar from a date editor. All platforms now support this style, and the `HINT` keyword has been removed from the `SWT.DROP_DOWN` style bit.