Packaging and Deploying Extensions

5 Packaging and Deploying Extensions

This chapter describes how to create a package to distribute your extension.

This chapter includes the following sections:

About Packaging and Deploying Extensions

Prior to the deployment of an extension, it has to be created and then packaged in an extension JAR file.

The steps to package and deploy an extension are as follows:

First, you create an extension package which consists of a JAR that is packaged in an extension bundle archive. The extension bundle archive is a JAR file containing the extension JAR and any supporting files used by the extension.
The extension JAR file contains:
- The extension manifest file extension.xml.
- Compiled class files and resources in the same directory structure they had while they were being developed.
The extension bundle archive contains:
- One or more extension JAR files.
- Any supporting files such as library JAR files.
Next, you package the extension JAR files into a .zip file for distribution.
If this is the first time you have opened the project in JDeveloper, for example if you are migrating an extension written for an earlier version of JDeveloper, right-click the project in the Applications window and choose Deploy to Target Platform. This generates the bundle manifest manifest.mf if one does not already exist. You may need to refresh the Applications window.
If the extension references external libraries, open the bundle manifest manifest.mf by locating it in the Applications window under the META-INF node, and change the line
```
Bundle-ClassPath: .
```
so that it says:
```
Bundle-ClassPath: .,external:jdev-install/jdeveloper/jdev/extensions/library
```

Packaging the Extension

Learn how to package JDeveloper extensions for deployment.

When you create an extension project, an extension deployment profile to create an OSGi bundle is also created. For more information, see "Deployment Profiles" in Developing Applications with Oracle JDeveloper.

How to Create the Deployment Profile

You set the OSGi bundle profile parameters from the Project Properties dialog.

To edit the deployment profile:

In the Applications window, right-click the project, then choose Properties. Alternatively, choose Project Properties from the Application menu.
Select Deployment in the panel on the left of the Project Properties dialog. The extension profile Extension (Extension JAR) is selected. Click Edit.
In the Bundle Options page of the OSGi Bundle Profile dialog, you can enter details such as the bundle name, version, and activator. For more help at any time, press F1 or click Help from the dialog.

You set dependencies and set libraries for inclusion by choosing other pages in the dialog. For more information, see Understanding Dependencies.

Click OK when you are finished editing the deployment profile properties.

How to Create the OSGi Bundle

Once you have edited the deployment profile you can create the OSGi Bundle.

To create the OSGi Bundle:

In the Applications window, right-click the extension project and choose Deploy > extension-profile to open the Deploy Extension dialog.
The option Deploy to OSGi Bundle is selected. You can click Next to examine details of the bundle that will be created in the Summary page. When you are satisfied, click Finish.

The OSGi bundle containing your extension is created in the Oracle-home/jdeveloper/jdev/extensions directory.

You can run and debug the OSGi bundle from this location automatically. For more information, see Testing and Debugging Extensions .

Deploying an Extension

Learn how to deploy JDeveloper extensions.

Extensions can be distributed to a team by making them available on a file system, and having users install the extension using the Check for Updates wizard available from the Help menu. See "Working with Extensions".

Alternatively, you can make an extension available to a wider audience by hosting it on the Web somewhere, or you could have it hosted as an open source project so that other people can help you enhance your extension and further develop it.

Oracle hosts some JDeveloper third party extensions, which are available at http://www.oracle.com/technetwork/developer-tools/jdev/index-099997.html. If you would like to upload your extension to this site, post a message on the JDeveloper and ADF forum at https://forums.oracle.com/forums/forum.jspa?forumID=83.

How to Publish an Extension in an Update Center

Once you have written and tested an extension for JDeveloper you can make it available in a JDeveloper Update Center, from where users can download it and have it automatically install on top of their JDeveloper installation.

Update centers for JDeveloper extensions are online at http://www.oracle.com/technetwork/developer-tools/jdev/index-099997.html, including the Oracle JDeveloper Third Party Extension Exchange which lists extensions developed by third-party companies and individual developers.

For information about how users install updates using the JDeveloper Update Center, see Working with the Extension Manifest.

In order for your extension to be installable using JDeveloper’s Check for Updates feature:

Create a bundle.xml file for the extension.
In Project Properties, create a Jar deployment profile which uses the file extension .zip rather than .jar.
With Profile Dependencies selected, ensure that the extension project is selected.
With File Groups selected, create a new file group for bundle.xml and specify the target directory as META-INF.
When you deploy the project using the new deployment profile the ZIP file is created, and this can be used on its own to distribute the extension. However, if you want to distribute the extension using an update center you have to create an update center XML file.
If you want to distribute the extension using an update center you have to create an update center XML file. Then in the Check for Updates dialog (available from the Help menu) to create a new update center pointing to the URL in the update center XML file.

You can have users add the new update center to their instance of JDeveloper so that they can download and install your extension.

Extension bundle.xml Document

This describes the bundle.xml document which you need to deploy and distribute an extension.

bundle.xml

Create a document called bundle.xml similar to the following example.

Note:

The metadata in bundle.xml must contain the u namespace, as shown in the example below.

<?xml version = '1.0' encoding = 'UTF-8'?>
<update-bundle version="1.0"
  xmlns="http://xmlns.oracle.com/jdeveloper/updatebundle"
  xmlns:u="http://xmlns.oracle.com/jdeveloper/update">
   <u:update id=" organization.dev.extension ">
    <u:name>Name of Extension</u:name>
    <u:version>1.0</u:version>
    <u:author>YourOrganization</u:author>
    <u:author-url> http://www.organization.com/dev/index.html/</u:author-url>
    <u:description>Provides support for a feature.
    </u:description>
    <u:requirements>
      <u:requires-extension id="oracle.jdeveloper"
        minVersion="12.1.2"
        maxVersion="12.2.1" />
      </u:requires-agreement url="META-INF/agreement.html" />
      </u:requirements> 
    <u:destination>${oracle.home}</u:destination> 
  </u:update>
</update-bundle>

Important Elements and Attributes

Element or Attribute

Description

Update Id

Each extension is identified by a unique id and the JDeveloper update center will refer to your extension using it.

Destination

This optional attribute is the install location and two macro values are available:

oracle.home, (default) the JDeveloper directory, for example, C:\oracle\middleware\jdeveloper.
oracle.mw.home, which can be used when you want to install extensions or patches in the middleware home directory above the jdeveloper directory, for example, C:\oracle\middleware .

Requires Agreement

This optional attribute which brings up the specified URL in the default browser for the user to provide agreement for using some technology.

Requires Extension minVersion and maxVersion

Use to specify the JDeveloper versions that the extension is for.

Update Center XML Document

This describes the update center XML document which you need to distribute an extension from an update center through JDeveloper’s Check for Updates feature.

Update Center XML File

The update center file is similar to bundle.xml but it has an additional element, bundle-url, which specifies the location of the extension ZIP file. For more information about bundle-url, see .

<?xml version = '1.0' encoding = 'UTF-8'?>
<update-bundle version="1.0"
  xmlns="http://xmlns.oracle.com/jdeveloper/updatebundle"
  xmlns:u="http://xmlns.oracle.com/jdeveloper/update">
   <u:update id=" organization.dev.extension ">
    <u:name>Name of Extension</u:name>
    <u:version>1.0</u:version>
    <u:author>YourOrganization</u:author>
    <u:author-url> http://www.organization.com/dev/index.html/</u:author-url>
    <u:description>
    </u:description>
    <u:requirements>
      <u:requires-extension id="oracle.jdeveloper"
        minVersion="12.1.2"
        maxVersion="12.2.1" />
    </u:requires-agreement url="META-INF/agreement.html" />
    </u:requirements> 
    <u:destination>${oracle.home}</u:destination> 
     <u:bundle-url> http://www.organization.com/dev/extension.zip/</u:bundle-url>
  </u:update>
</update-bundle>