Using the PEAR Eclipse Plugin involves the following two steps:

• Add the UIMA nature to your project
• Create a PEAR file using the PEAR generation wizard

Add UIMA Nature to your project

First, create a project for your UIMA component:

• Create a Java project, which would contain all the files and folders needed for your UIMA component.
• Create a source folder called "src" in your project, and make it the only source folder, by clicking on "Properties" in your project’s context menu (right-click), then select "Java Build Path", then add the "src" folder to the source folders list, and remove any other folder from the list.
• Specify an output folder for your project called bin, by clicking on "Properties" in your project’s context menu (right-click), then select "Java Build Path", and specify "your_project_name/bin" as the default output folder.

Then, add the UIMA nature to your project by clicking on "Add UIMA Nature" in the context menu (right-click) of your project. Click "Yes" on the "Adding UIMA custom Nature" dialog box. Click "OK" on the confirmation dialog box.

17. Adding the UIMA Nature

Adding the UIMA nature to your project creates the PEAR structure in your project. The PEAR structure is a structured tree of folders and files, including the following elements:

• Required Elements:
  • The metadata folder which contains the PEAR installation descriptor and properties files.
  • The installation descriptor (metadata/install.xml)
• Optional Elements:
  • The desc folder to contain descriptor files of analysis engines, component analysis engines (all levels), and other component (Collection Readers, CAS Consumers, etc).
  • The src folder to contain the source code
  • The bin folder to contain executables, scripts, class files, dlls, shared libraries, etc.
  • The lib folder to contain jar files.
  • The doc folder containing documentation materials, preferably accessible through an index.html.
  • The data folder to contain data files (e.g. for testing).
  • The conf folder to contain configuration files.
  • The resources folder to contain other resources and dependencies.
  • Other user-defined folders or files are allowed, but should be avoided.

For more information about the PEAR structure, please refer to the "Processing Engine Archive" section.

Use the PEAR Generation Wizard

Before using the PEAR Generation Wizard, make sure you add all the files needed to run your component including descriptors, jars, external libraries, resources, and component analysis engines (in the case of an aggregate analysis engine), etc. It’s recommended to generate a jar file from your code as an alternative to building the project and making sure the output folder (bin) contains the required class files.

Then, click on "Generate PEAR file" from the context menu (right-click) of your project, to open the PEAR Generation wizard, and follow the instructions on the wizard to generate the PEAR file.

The Component Information page

The first page of the PEAR generation wizard is the component information page. Specify in this page a component ID for your PEAR and select the main Analysis Engine descriptor. The descriptor must be specified using a pathname relative to the project’s root (e.g. "desc/MyTAE.xml). The component id is a string that uniquely identifies the component. It should use the JAVA naming convention (e.g. com.ibm.uima.mycomponent).

Optionally, you can include specific Collection Iterator, CAS Initializer, or CAS Consumers. In this case, specify the corresponding descriptors in this page.

Figure 19. The component Information page

The Installation Environment page

The installation environment page is used to specify the following:

• Preferred operating system
• Required JDK version, if applicable.
• Required Environment variable, such as CLASSPATH

Path names should be specified using macros (see below), instead of hard-coded absolute paths that might work locally, but probably won’t if the PEAR is deployed in a different machine and environment.

Macros are variables such as $main_root, used to represent a string such as the full path of a certain directory.

These macros should be defined in the PEAR.properties file using the local values. The tools and applications that use and deploy PEAR files should replace these macros (in the files included in the conf and desc folders) with the corresponding values in the local environment as part of the deployment process.

Currently, there are two types of macros:

• $main_root , which represents the local absolute path of the main component root directory after deployment.
• $component_id$root, which represents the local absolute path to the root directory of the component which has component_id as component ID. This component could be, for instance, a delegate component.

The Installation Environment Page

The PEAR file content page

The last page of the wizard is the "PEAR file Export" page, which allows the user to select the files to include in the PEAR file. The metadata folder and all its content is mandatory. Make sure you include all the files needed to run your component including descriptors, jars, external libraries, resources, and component analysis engines (in the case of an aggregate analysis engine), etc. It’s recommended to generate a jar file from your code as an alternative to building the project and making sure the output folder (bin) contains the required class files.

Note: If you are relying on the class files generated in the output folder (usually called bin) to run your code, then make sure the project is built properly, and all the required class files are generated without errors. In this case make sure your output folder (e.g. $main_root/bin) is in the classpath (see the "Installation Environment" page.

The PEAR File Export Page