EGL projects, packages, and files

An EGL project includes zero to many source folders, each of which includes zero to many packages, each of which includes zero to many files. Each file contains zero to many parts.

EGL project

An EGL project is characterized by a set of properties, which are described later. In the context of an EGL project, EGL automatically performs validation and resolves part references when you perform certain tasks; for example, when you save an EGL file or build file. In addition, if you are working with page handler parts (the output of which is used to debug Web applications in the Websphere test environment), EGL automatically generates output, but only in this case:

You have set the automatic build process after selecting these options: Window > Preferences > Workbench > Perform build automatically on resource modification
You have established a default build descriptor as a preference or property

An EGL project is formed by selecting EGL or EGL Web as the project type when you create a new project. You assign properties while working through the steps of project creation. To begin modifying your choices after you have completed those steps, right-click the project name and when a context menu is displayed, click Properties.

The EGL properties are as follows:

EGL source folder

One or more project folders that are the roots for the project's packages, each of which is a set of subdirectories. A source folder is useful for keeping EGL source separate from Java files and for keeping EGL source files out of the Web deployment directories. It is recommended that you specify EGL source folders in all cases; but if a source folder is not specified, the only source folder is the project directory.

The value of this property is stored in a file named .eglpath in the project directory and is saved in the repository (if any) that you use to store EGL files.

The EGL project wizards each create one source folder named EGLSource.

EGL build path

The list of projects that are searched for any part that is not found in the current project.

The value of this property is stored in a file named .eglpath in the project directory and is saved in the repository (if any) that you use to store EGL files.

In the following example of an .eglpath file, EGLSource is a source folder in the current project, and AnotherProject is a project in the EGL path:

  <?xml version="1.0" encoding="UTF-8"?>
  <eglpath>
    <eglpathentry kind="src" path="EGLSource"/>
    <eglpathentry kind="src" path="\AnotherProject"/>
  </eglpath>

The source folders for AnotherProject are determined from the .eglpath file in that project.

Default build descriptors

The build descriptors that allow you to generate output quickly, as described in Generation in the workbench.

Package

A package is a named collection of related source parts.

By convention, you achieve uniqueness in package names by making the initial part of the package name an inversion of your organization's Internet domain name. For example, the IBM domain name is ibm.com, and the EGL packages begin with "com.ibm". By using this convention, you gain some assurance that the names of Web programs developed by your organization will not duplicate the names of programs developed by another organization and can be installed on the same server without possibility of a name collision.

The folders of a given package are identified by the package name, which is a sequence of identifiers separated by periods (.), as in this example:

  com.mycom.mypack

Each identifier corresponds to a subfolder under an EGL source folder. The directory structure for com.mycom.mypack, for example, is \com\mycom\mypack, and the source files are stored in the bottom-most folder; in this case, in mypack. If the workspace is c:\myWorkspace, if the project is new.project, and if the source folder is EGLSource, the path for that package is as follows:

  c:\myWorkspace\new.project\EGLSource\com\mycom\mypack

The parts in an EGL file all belong to the same package. The file's package statement, if any, specifies the name of that package. If you do not specify a package statement, the parts are stored directly in the source folder and are said to be in the default package. It is recommended that you always specify a package statement because files in the default package cannot be shared by parts in other packages or projects.

Two parts with the same identifier may not be defined in the same package. It is strongly recommended that you avoid using the same package name under different projects or different folders.

The package for generated Java output is the same as the EGL file package.

EGL files

Each EGL file belongs to one of these categories:

Source file

An EGL source file (extension .egl) contains logic, data, and user interface parts and is written in EGL source format. Parts of the following kinds are called primary parts:

DataTable
FormGroup
Library
PageHandler
Program

Other parts are called subparts.

An EGL source file can include zero to many subparts but can include no more than one primary part. The primary part (if any) must be at the top level of the file and must have the same name as the file.

Build file

An EGL build file (extension .eglbld) contains any number of build parts and is written in Extensible Markup Language (XML), in EGL build-file format. You can review the related DTD, which is in the following directory:

installationDir\egl\eclipse\plugins\
com.ibm.etools.egl_version

installationDir: The product installation directory, such as C:\Program Files\IBM\RSPD\6.0. If you installed and kept a Rational Developer product before installing the product that you are using now, you may need to specify the directory that was used in the earlier install.
version: The installed version of the plugin; for example, 6.0.0

The file name (like egl_wssd_6_0.dtd) begins with the letters egl and an underscore. The characters wssd refer to Rational Web Developer and Rational Application Developer; the characters wsed refer to Rational Application Developer for z/OS; and the characters wdsc refer to Rational Application Developer for iSeries.

After you add parts to files, you can use a repository to maintain a history of changes.

Recommendations

This section gives recommendations for setting up your development projects.

For build descriptors

Team projects should appoint one person as a build-descriptor developer. The tasks for that person are as follows:

Create the build descriptors for the source-code developers
Put those build descriptors in a project separate from the source code projects; and make that separate project available in the repository or by some other means
Ask the source-code developers to set the property default build descriptors in their projects, so that the property references the appropriate build descriptors
If a small subset of the build descriptor options (such as for user ID and password) varies from one source-code developer to the next, ask each source-code developer to do as follows:
- Code a personal build descriptor that uses the option nextBuildDescriptor to point to a group build descriptor
- Ask the source-code developers to set the property default build descriptors in their files, folders, or packages, so that the property references the personal build descriptor. They do not specify the property at the project level because the project-level property is under repository control, along with other project information.

For additional information, see Build descriptor part.

For packages

For packages, recommendations are as follows:

Do not use the same package name in different projects or source directories
Do not use the default package

Part assignment

For parts, many of the recommendations refer to good practices, not hard requirements. Fulfill even the optional recommendations unless you have good reason to do otherwise:

A requirement is that you put JSPs in the same project as their associated page handlers.
If a non-primary part (like a serial record part) is used only by one program, library, or page handler, place the non-primary part in the same file as the using part.
If a part is referenced from different files in the same package, put that part in a separate file in the package.
If a part is shared across packages in a single project, place that part in a separate package in that project.
Put code for completely unrelated applications in different projects. The project is the unit for transferring code between your local directory structure and the repository. Design project structure so that developers can minimize the amount of code they have to have loaded into their development system.
Name projects, packages, and files in a way that reflects the use of the parts they contain.
If your process emphasizes code ownership by a developer, do not assign parts for different owners to the same file.
Assign parts to packages with a clear understanding of the purpose of the package; and group those parts by the closeness of the relationship between them.
The following distinction is important:
- Moving a part from file to file in the same package does not require that you change import statements in other files.
- Moving a part from one package to another may require an import statement to be added or changed in every file that references the moved part.