Chapter 4 Managing Applications and Packages in Jaguar Manager

Defining packages

In Jaguar Manager, a package contains a group of related components. Typically, components in a package work together to provide a coherent service or function.

Refresh when you modify a package, component, or method When you modify an existing package, component, or method, you must refresh the server, package, or component for the changes to take effect. To refresh, highlight the icon for the server, package, or component and select File | Refresh. If you modify a component's supported interfaces, you must regenerate stubs and skeletons for the component and clients that access the component.

You must install your components in packages before applications can access the components. Packages serve the following purposes:

They are a unit of deployment Using Jaguar Manager, you can import and export archived copies of the components in a package and related application files.
They allow you to control which users can access components Packages form one level in the Jaguar authorization hierarchy. A package is not available on a server unless it is installed in the server's Installed Packages folder. To further restrict access for non-EJB components, you can edit the package's required Role Memberships to restrict which users can access components in the package. You can also control access on the individual component level. "Declarative security" describes options for configuring user authorization for package and component access. EJB components use a different security mechanism described in "Configuring role references and method permissions".
In a cluster, they allow you to partition the load By installing different subsets of packages to the servers in a cluster, you can control which components execute on which servers within the cluster. See "Load Balancing and Failover" in the Jaguar CTS System Administration Guide for more information.

Use Jaguar Manager to create, modify, and delete packages, as described in the sections below:

Creating a new package

You can create a new package that does not yet belong to any Jaguar server by following these steps:

Start Jaguar Manager if it is not running, and connect to your server.
Expand the Jaguar Manager icon.
Highlight the Packages icon.
Select File | New Package.
Enter the name of the new package. The name must not match any existing package defined in the Jaguar repository. To avoid name collisions, you can use the Java reverse domain naming style; for example, "com.foo.finance."
Supply the package information. The properties are described in "Configuring package properties ".

The new package appears on the right side of the screen when you highlight the package icon.

Package names are not case sensitive and must be unique Your packages must have unique names that differ in ways other than letter case. For example, you cannot define two packages named MyPack and mypack in the same Jaguar installation. You cannot have two packages with the same name, even if one is installed in an application and the other is not.

Installing packages to a server

Except for packages used internally by Jaguar, packages to be run on a Jaguar server must be installed in that server, using one of two methods:

Add the package to the server's Installed Packages folder.
Add the package to an application's Installed Packages folder, then install the application to the server. See Chapter 4, "Managing Applications and Packages in Jaguar Manager" describes this method.

Packages that you create must be installed in a server before that server's clients can access components in the package.

You can only install a package in one application. Once a package is installed in an application, it cannot be installed directly in a server.

Default packages

Jaguar includes a set of default packages that include components used internally by Jaguar. These packages are available whether or not they are installed to a server's Packages folder. Currently, these include the packages: Jaguar, Jaguar1, CosNaming, CtsSecurity, CtsServlet, DataWindow, EventSamples, and PBDebugger. The list of default packages is subject to change without notice.

Installing packages

Double-click the Servers folder to expand it.
Double-click the server (listed on the left side of the screen) to which you want to install a package.
Highlight the Installed Packages icon. A list of installed packages appears on the right.
Select File |Install Package. Then select one of the following options from the Package Wizard:
- Install an existing package A list of uninstalled packages appears in the dialog box. Highlight the package you want to install, and click Ok.
- Create and install a new package Enter the name of the new package you want to install. Supply the package information, and click Ok. The properties are described in "Configuring package properties ".

Modifying packages

To modify an existing package:

Highlight the package you want to modify. You can highlight the package icon displayed in a server's package folder or in the main Packages folder (both icons represent the same package as long as the package names are identical).
From the File menu, select one of the following options:
- Package Properties Displays the Package Properties window described in "Configuring package properties ". Make any modifications required, and click Ok.
- Remove Package If you have selected a package that is installed on a server, this option removes the package from the server.
- Delete Package If you have selected an uninstalled package, this option deletes the package from the system.

Default packages cannot be modified or deleted Jaguar's default packages cannot be modified or deleted, and you cannot modify or delete components installed in default packages. These components are run internally by Jaguar. See "Default packages" for more information.

Configuring package properties

The Package Properties window has two tabs, General and All Properties.

Package properties: General tab

The following table describes the properties on the General tab.

Table 4-1: Package properties: General tab
Property	Description	Comments/example
Description	A description of the package. The description can be up to 255 characters.	View or change the description of an existing component or set the description of a new one.

Role Mapping properties

These settings map role names used in the packages EJB 1.1 components to role names that exist in Jaguar Manager.

To map a J2EE role to a Jaguar role:

If necessary, define a new Jaguar role. See the Jaguar CTS Administration Guide for instructions.
Select the Role Mapping tab from the Web application properties window.
Click Add. Double-click the J2EE role and enter a name. You can also enter a description for the role in the provided field.
Select a Jaguar role from the drop-down list. This is the role from which the J2EE role inherits its permissions and members.

All Properties settings

The All Properties tab allows you to edit package property settings as they are stored in the Jaguar configuration repository. You can only delete properties that you have added--you cannot delete default properties, such as the com.sybase.jaguar.package.components property.

You can set properties as follows:

Look for the property name in the list of properties. If it is displayed, highlight the property and click Modify. Otherwise, click Add.
If adding the property, fill in the Add Property fields as follows:
- Enter the property name in the Name field
- Enter the value in the Value field.
If modifying a property, edit the displayed value in the Modify Property window.

com.sybase.jaguar.package.files property Specifies additional files that are to be archived when the package is exported or replicated to another server with the synchronize feature. The rules for setting this property are the same as for the com.sybase.jaguar.component.files property. See "Component files property" for more information. The only way to set this propery is on the All Properties tab.

Repository property names are listed in the documentation for the Jaguar::Repository IDL interface, in the description of the define method. To read this documentation, load your server's main HTML page into a Web browser, and follow the Interface Repository link.

When to use the All Properties tab Though you can use the All Properties tab to set any property prefixed with com.sybase.jaguar.package, Sybase recommends that you use this tab to set properties only as specified by the Jaguar documentation or by Sybase Technical Support. Most properties can be configured graphically elsewhere in the Jaguar Manager user interface.

Using package export and import

Jaguar Manager allows you to create an archive file containing component definitions and implementation files for all components in a package. You can export archive files from packages on your development server and import them to your production server.

To deploy packages between servers using archive files

Start Jaguar Manager on the test server host and connect to the test server.
Optionally, configure the package properties to specify the list of additional files to be included in the package archive. In the Package Properties window, you can use the All Properties tab to set the com.sybase.jaguar.package.files property, as described in "Configuring package properties ".

By default, all component implementation files and required stub files are included in the archive. You may want to include other files, such as project descriptions, client applets, and HTML pages. You can specify additional files either by setting the package properties or when generating the package archive.
Export an archive of the application's Jaguar packages. This step creates a Java archive (JAR) file containing the component definition files and implementation files. "To export a package archive" describes this step in detail.
Copy the JAR file to the production server.
Start Jaguar Manager on the production server host, and connect to the production server.
Import the JAR file containing the package archive into the production server. "To import a package archive" describes this step in detail.
If you have copied the package between host machines that have different architectures, recompile the components to run on the new architecture.

To export a package archive

Start Jaguar Manager, and connect to the server where the package is installed.
Highlight the package you are exporting.
Select File | Export JAR File.
The Export dialog box appears.

For each C/C++ component in your package, provide the name of the corresponding DLL or shared-library file. No input is required for Java components.
Click the Misc. Information button to add any other files that you want to include with the package. These files can include HTML files, project files, and so on.

Use the Browse, Add, and OK buttons to add other files to the JAR file. To delete a miscellaneous file, highlight the file and click Delete. Click Done when all the files you want to include are listed in the dialog box.
Click OK.

The exporter locates the Java class and C/C++ shared library files and combines them with the miscellaneous files you selected into a JAR file.

To import a package archive

Copy the JAR file containing the package definition to the host machine for the target Jaguar server.
Start Jaguar Manager and connect to the target server.
Expand the Packages folder and verify that the package to be imported does not already exist. If it does, select it and delete the package.
Highlight the packages folder, and select File | Import.
The Import dialog box appears:
- Use the Browse button to locate the JAR file that you are importing.
- Enter the full path of the directory where you want the archive to be unbundled. This directory becomes the root directory from which the JAR file is unbundled. Unbundling creates the subdirectories, class files, DLLs, and any other files that were included in the exported JAR file.
Click Import.