From: Paul Davies <Paul-Martin.Davies_at_Sun.COM>
Date: Tue, 23 Oct 2007 17:29:42 -0700

Hi,

Please review the attached HTML files, which contain the additions and changes
to the GlassFish 9.1ur1online help to fix Issue Tracker Issue 3777
https://glassfish.dev.java.net/issues/show_bug.cgi?id=3777 .

Please give me your feedbcak by end of day Thursday October 25, 2007. I have
agreed to commit my changes to the CVS repository by end of day Friday.

The files are as follows:

jbi-common-upgradecomponent.html (new)
Online help for the Upgrade JBI Component page.
http://wiki.open-esb.java.net/Wiki.jsp?page=SierraUpdateWebConsole#section-SierraUpdateWebConsole-IIAUpgradeComponent

jbi-common-show-component-shared-library-dependencies.html (new)
Online help for the Libraries tab of the component window
http://wiki.open-esb.java.net/Wiki.jsp?page=SierraUpdateWebConsole#section-SierraUpdateWebConsole-IIC1UseCases

jbi-common-show-shared-library-component-dependencies.html (new)
Online help for the Components tab of the library window
http://wiki.open-esb.java.net/Wiki.jsp?page=SierraUpdateWebConsole#section-SierraUpdateWebConsole-IIC1UseCases

jbi.common.showServiceUnit=jbi-common-showserviceunit.html (new)
Online help for the Service Unit General Information page.
http://wiki.open-esb.java.net/Wiki.jsp?page=SierraUpdateWebConsole#section-SierraUpdateWebConsole-IIBShowServiceUnits

showmetadata.html (changed)
Online help for the Service Unit Descriptor tab. Modified to add information
about metadata for a service unit. Shared by other JBI Descriptor tabs.
http://wiki.open-esb.java.net/Wiki.jsp?page=SierraUpdateWebConsole#section-SierraUpdateWebConsole-IIBShowServiceUnits

Thank you.

-- 
Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
http://blogs.sun.com/techscribe/

To Upgrade a JBI Component

Upgrading a JBI component replaces a service engine or a binding component with a different version of the component. Upgrading a JBI component enables you to replace the component without the need to redeploy any service assemblies that are already deployed. You may upgrade to a later version or an earlier version of the component.

If the component that you are upgrading implements the upgrade method, the component obtains the paths to the directories of the previously installed version and the replacement version. This information enables the component to perform additional processing, for example, creating and deleting database tables.

---

Note - An upgrade to a JBI component applies to all targets. In domains that are configured to support clusters, you cannot upgrade a component on only a subset of available targets.

---

You can upgrade a component only if the component name remains unchanged after the upgrade. The component name is defined in the JBI metadata of the component archive.

Before You Begin

Ensure that the following prerequisites are met:

• The component that you are upgrading is shut down.

• You have the location of the archive file that contains the replacement version of the component.

• In domains that are configured to support clusters, all targets where the component is installed are started.

1. In the tree component, expand the JBI node.
2. Under the JBI node, select Components.

   The Components page opens.

3. In the Action column of the JBI Binding Components and Service Engines table, follow the Upgrade link for the component that you are upgrading.

   The Upgrade Component page opens.

4. In the Upgrade Component page, specify the archive file of the replacement version of the component.
   • If the file is located on the machine where your web browser is running, specify the file as follows:
     1. Select the Package File to Be Uploaded to the Application Server option.
     2. In the File to Upload field, specify the full path to the file.
   • If the file is located on the machine where the Domain Administration Server (DAS) is running, specify the file as follows:
     1. Select the Package File That is Accessible From the Server option.
     2. In the File to Copy field, specify the full path to the file.
5. Click Upgrade.

   After a successful upgrade, the directories of the previously installed version are deleted.

Troubleshooting

The replacement version of a component might not work with previously deployed Service Assemblies when the component is started after an upgrade. In this situation, perform the following sequence of operations to upgrade the component:

• Undeploying all Service Assemblies

• Uninstalling the existing version of the component

• Installing the replacement version of the component

• Redeploying all Service Assemblies

If the archive file of the replacement version is inconsistent with the archive file of the original version, the upgrade fails. If an upgrade fails, the directories of the replacement version are deleted.

Viewing Shared Libraries That Are Used by a Component

This page provides information about the installed Shared Libraries that this component requires. The information Includes the name of the Shared Library and a brief description.

Viewing Components That Depend on a Shared Library

The Components tab provides information about the components that require the selected Shared Library. The information includes the name of the component, the component type and a brief description.

To View the General Properties of a Service Unit

1. In the tree component, expand the JBI→Service Assemblies node.
2. Under the Service Assemblies node, expand the node for the Service Assembly that contains the Service Unit.
3. Select the Service Unit whose general information you are viewing.

   The Service Unit General Information page opens. This page provides the following information about the selected service unit:

   • The name of the Service Unit

   • A brief description of the Service Unit

   • The name of the Service Assembly to which the Service Unit belongs

   • The Target Component of the Service Assembly

Viewing JBI Descriptors

The Descriptor tab displays the contents of the descriptor file (jbi.xml) for Service Assemblies, Service Units, JBI components, and Shared Libraries. This file provides the following information:

• Service Assemblies: Lists the Service Units contained in the Service Assembly and the target for each Service Unit. Some Service Units may also show information on connection endpoints.

• Service Units: Indicates whether the Target Component of the containing Service Assembly is a binding component.

• JBI components: Lists the type of the JBI component (Binding Component or Service Engine), a description of the component, information about relevant classpaths for the component, and the name of any Shared Libraries upon which it depends.

• Shared Libraries: Lists the name of the Shared Library, and the names of the archive files (.jar files) or class file subdirectories it contains.