Chapter 9: Importing and Exporting Application Components

Deploying packages and components

Components must be archived as part of the package where they are installed. You can archive in two formats:

EAServer JAR This format, while proprietary to EAServer, supports all component types. Also, unlike the EJB-JAR format, all component property settings are preserved in the archive.
EJB JAR This format provides portability between J2EE and EJB servers from different vendors. Only EJB components are archived in this format; components of other types are ignored when you create the archive. Not all component properties are preserved in the archive, because the deployment descriptor does not support all EAServer properties. These EAServer properties can be configured by including an EAServer XML configuration file in the archive, as described in “Using EAServer configuration files in J2EE archives”. The following settings in the Component Properties dialog box are not configured by the EJB-JAR deployment descriptor, and must be configured in the XML configuration file or manually after deployment:
- For beans that use container-managed persistence, the Persistence settings.
- Role mappings and method-level permissions.
- Resource references.
- EJB references to components that are not installed with the JAR file or when multiple beans use the same home and remote interfaces. It is impossible to infer EJB references if more than one bean uses the home and remote interfaces specified by the reference properties in the deployment descriptor. After importing an EJB-JAR file that contains multiple beans that use the same home and remote interfaces, view the EJB Reference properties to verify that the correct bean is invoked.
- Environment properties.
- For EJB 2.0 components, Resource Environment Refs properties.
- For EJB 2.0 components, Run As Identity properties.
For information on these properties, see the EAServer Manager online help or the EAServer Programmer’s Guide.
EJB 1.0 JAR This format supported for backward compatibility. It is similar to the EJB-JAR format, but supports only EJB version 1.0 components. For more information on this format, see Appendix A, “Using EJB 1.0 JAR Support.”

Importing and exporting components in EAServer JAR format

EAServer Manager allows you to create an archive file containing component definitions and implementation files for all components in a package or a single component. You can export archive files from packages on your development server and import them to your production server. If the JAR file contains a single component, it must be installed to a package with the same name as the one from which it was exported.

Deploying packages between servers using archive files

Start EAServer 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 Additional Files tab to set the com.sybase.jaguar.package.files property, as described in the online help.

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 or component properties or when generating the package archive.
Export an archive of the application’s EAServer packages. This step creates a Java archive (JAR) file containing the component definition files and implementation files. “Exporting a package archive” describes this step in detail.
Copy the JAR file to the production server.
Start EAServer Manager on the production server host, and connect to the production server.
Import the JAR file containing the package archive into the production server. “Importing 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.

Exporting a package archive

Start EAServer Manager, and connect to the server where the package is installed.
Highlight the package you are exporting.
Select File | Export | EAServer JAR.
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.

Importing a package archive

Copy the JAR file containing the package definition to the host machine for the target server.
Start EAServer 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.

Exporting a component as an EAServer JAR file

Highlight the icon for the component you are exporting. .
Select File | Export | EAServer JAR.
The Export dialog box appears. Enter the full path of the directory where the JAR file is to be created.
Click OK. EAServer Manager creates the file name component.jar, where component is the name of the selected component.

Importing a single component from an EAServer JAR file

If the JAR file contains a single component, it must be installed in a package with the same name as the one where it was originally installed. Create this package if necessary. Import the component as follows:

Highlight the package from which the component was exported.
Choose File | Deploy | EAServer JAR.
Use the Browse button to select the JAR file, or type the full path to the file.
Click OK to begin importing.

Importing and exporting packages in EJB-JAR format

An EJB-JAR file contains the implementation classes, interface classes, and deployment descriptor for one or more beans. You can use a Java development tool such as Sybase PowerJ to define and develop beans and create an EJB-JAR file. You can import JAR files in the EJB 1.0, EJB 1.1, or EJB 2.0 formats. EAServer Manager reads the JAR file and creates a package containing a component for each bean in the JAR file.

PowerJ deploys Enterprise JavaBeans directly to EAServer If you are developing in PowerJ, use the Enterprise JavaBeans Deployment Wizard to install EJB components to EAServer. If using another IDE, use EAServer Manager to import the bean as described below.

Importing an EJB 1.1 or 2.0 JAR file

Start EAServer Manager if it is not already running, and connect to the server where you want to install the component.
Highlight the top-level Packages folder. Choose File | Deploy | EJB JAR.
Enter the path to the EJB-JAR file.

Choose the Deployment Strategy from the options described in Table 9-1.

**Table 9-1: Deployment strategy options**
Deployment strategy	Specifies
Full deployment	The importer generates IDL for every class defined in the JAR, regardless of whether the interface already exists. Use this option when deploying components for the first time or when you want to restore IDL types that have been changed or deleted.
Incremental deployment	The importer generates IDL only when the Java types and interfaces have changed from the last time it was imported. The following are compared: Methods Fields Interfaces Superclass Use this option if you redeploying components and have changed some interfaces or parameter types.
Optimistic deployment	Similar to Incremental, except that the check for changed classes in each package ends if the first class comparison indicates no change. Use this option if you are redeploying components, and have changed only the implementation classes.

Configure the Deployment Options:
- Prompt before overwriting existing objects If selected, the importer will confirm any overwrites of existing components, IDL definitions, and other repository entities that may be redefined by the import process.
- Automatically generate EJB stubs and skeletons Select this option if you want the importer to generate and compile stubs and skeletons for the new components. To allow compilation, the classes in the EJB-JAR file must be self-contained, in other words classes in the JAR file cannot depend on classes that are not in the JAR file or part of the standard J2EE class distribution.
  
  Home interfaces that use java.util.Enumeration Do not select the Automatically generate EJB stubs and skeletons option if entity bean finder methods return java.util.Enumeration. Instead, generate Stubs and Skeletons after the import completes, and select the JDK 1.3 or later option.
  
  All entity bean finder methods within one EJB JAR file must return the same list type, either java.util.Collection or java.util.Enumeration.
- Use interoperable naming If selected, naming URLs in the EJB Reference properties will use interoperable naming URLs, as described in “Intervendor EJB interoperability” in the EAServer Programmer’s Guide. Select this option when your EJBs have EJB references that link to another vendor's EJB 2.0 server and you need to use the RMI/IIOP protocol for the connection.
- Use JAR File Package Naming Naming If selected, the new package name will match the EJB-JAR file name. Otherwise the new package name matches the display-name element in the deployment descriptor.
  
  When you are deploying an EAR or EJB-JAR file containing a sybase-easerver-config.xml file, which was previously exported from EAServer, do not use the JAR File Naming option. When exporting packages to a J2EE archive file, EAServer optionally creates a sybase-easerver-config.xml file that includes configuration information based on the package names. If you deploy a package or an application that contains packages with the JAR File Naming option, EAServer renames the packages. When the package names do not match the names in the sybase-easerver-config.xml file, deployment fails.
Click Finish.

EAServer Manager creates a new package that contains a component for each bean defined in the JAR file, printing status messages and warnings to the Deploy Wizard. The new package has the same name as the EJB JAR display name. If there is no display name, the new package has the same name as the JAR file. For each bean in the EJB-JAR, EAServer creates an EJB component with the same name as the ejb-name element in the EJB-JAR deployment descriptor.

Home names for imported EJB components EAServer sets an imported bean’s home name to the EAServer default, package/component, where package is the EAServer Manager package name, and component is the EAServer Manager component name.

Use the status dialog as a to-do list In the deployment status dialog box, EAServer Manager display warnings for each setting that requires further attention before running the application. You can copy and paste this text to a text editor to use as a to-do list.

Exporting EJB-JAR files

You can create an EJB-JAR file that contains the Java classes and deployment descriptors for the EJB components installed in an EAServer package. The JAR file can be deployed to another EAServer installation or any EJB compatible server.

You can export EJB-JAR files in two formats:

EJB JAR Use this format for exporting EJB 2.0 or 1.1 components. Components in the package of other types are not included in the JAR file. The file can be deployed to any EJB 2.0 server.
EJB 1.0 JAR Use this format for exporting EJB 1.0 components. Components in the package of other types are not included in the JAR file. The file can be deployed to any EJB 1.0 server. Appendix A, “Using EJB 1.0 JAR Support,” describes this option.

Use synchronization for deploying beans between servers The EAServer synchronization feature can also be used to deploy components from one EAServer installation to another. Synchronization is simpler than importing and exporting JAR files, but the source server must be able to connect to the target server. If you use synchronization, you will avoid the need to reconfigure JNDI resource references on the target server for EJB 2.0 or 1.1 components.

Exporting an EJB-JAR file

Highlight the EAServer package to export and choose File | Export, then choose EJB 1.0 JAR or EJB JAR.
Enter the path and file name for the new JAR file and click Next.
Optionally deselect the Export with EAServer XML Configuration File option if you do not want the archive to include an EAServer XML configuration file.
EAServer Manager creates the JAR file, displaying status messages in the Export wizard.