Package org.eclipse.wst.common.componentcore

The ComponentCore API allows clients to work with the Structural Metamodels that define abstract modules within Eclipse projects.

See:
Description

Interface Summary

IEditModelHandler

Provides a standard interface for managing the lifecycle of an Edit Model.

Class Summary

ArtifactEdit	Provides a Facade pattern for accessing Module Content Metamodels for Web Tools Platform flexible modules.
ComponentCore	Provides a handle creation factory for the Virtual Path API.
ModuleCoreNature	Allows projects to support flexible project structures.

Exception Summary

UnresolveableURIException

Thrown whenever a URI cannot be appropriately resolved.

Package org.eclipse.wst.common.componentcore Description

The ComponentCore API allows clients to work with the Structural Metamodels that define abstract modules within Eclipse projects. These metamodels are exposed through the Virtual Path API layer (see ComponentCore). Clients should also review the org.eclipse.wst.common.componentcore.resources package.

The following document includes information on these topics:

• ComponentCore Metamodel (CCM) used to understand which files should or should not be included within a module.
• Constraints enforced by the design
• The API entry-point

ComponentCore Metamodel (CCM)

The ComponentCore Metamodel (CCM) is an EMF model that allows the tooling to understand most project structures. Each project has a single CCM which is stored under the project root named .wtpmodules . The XML format is defined by the ComponentCore schema. The following diagram is a UML representation of the ComponentCore Metamodel. This information is published for potential contributors of editors, but the EMF model is not exposed directly as API, and could change in view of changes for WTP 1.1.

Figure 1: The Component Core Metamodel

Each logical component contained in the project is represented by a WorkbenchComponent element. The WorkbenchComponent defines information about the type of component, the resources consumed by the module from the project, and the referenced components. The WorkbenchComponent is very generic, and as modeled, does not necessarily correspond to only J2EE artifacts.

The WorkbenchComponent has a name , which is the name that will be used when the runtime form of the component is constructed. For a web application, the name might be "MyWebApplication".

The WorkbenchComponent may be uniquely referenced by a URI. The fully qualified URI to any component must begin with the component protocol ("component:"), specify a subprotocol ("resource|classpath") and then a path to the referenced component. A WorkbenchComponent with the name "MyWebApplication" defined in a project named "MyWebModulesProject" would be referenced by the following URI: "component:/resource/MyWebModulesProject/MyWebApplication". As a future extension, a component referenced on the classpath of a project (perhaps a Utility Jar or an EJB Client Jar), the URI might be something like: "component:/classpath/MyWebModulesProject/CustomerEJBClient.jar".

The WorkbenchComponent has a ComponentType. The ComponentType defines a componentTypeId , which indicates the specific kind of component. The Web Tools Platform uses the componentTypeId to determine how to work with the content component of the WorkbenchComponent and prepare the component for deployment. The ComponentType may also define the runtime-paths of special metadata resources which are important to the WorkbenchComponent. "Metadata" refers to resources which explain the content details of the specific modules. An example of such a file would be the "WEB-INF/web.xml" deployment descriptor for Web Applications.

The WorkbenchComponent contains a list of ComponentResources. Each ComponentResource has "sourcePath" and a corresponding "runtimePath". The "sourcePath" can reference either a file or folder, but the referenced resource must be contained in the same project as the WorkbenchComponent definition. The "runtimePath" specifies a location relative to the deployed structure of the WorkbenchComponent where the contents of the referenced resource will be represented when the module is prepared for runtime.

The WorkbenchComponent contains a list of ReferencedComponents. Each ReferencedComponent provides a handle that must resolve to a WorkbenchComponent, a runtimePath that defines where the constructed component will be placed within the context of the runtime WorkbenchComponent, and a DependencyType that can be either "consume" or "use" to indicate how the contents of that ReferencedComponent should be absorbed by the WorkbenchComponent. ReferencedComponents may reference WorkbenchComponents in other projects and on current project's classpath (Not yet implemented). The DependencyType will determine whether the contents of the ReferencedComponent are absorbed as-is or archived into a *.{w|j|e}ar file.

The ProjectComponents object provides a root container for all WorkbenchComponents defined in a given project.

ComponentCore provides a facade to manage the underlying model for clients. Static methods ModuleCore.getModuleCoreForRead() and ModuleCore.getModuleCoreForWrite() may be used to acquire an ModuleCore adapter, and clients are responsible for invoking dispose() whenever they are finished using the model.

top

Constraints enforced by the CCM

The following constraints are enforced by the model:

1. The solution will not check dependencies for components that are contained in the same project. To get the full benefits of inter-component dependency checking, components must be separated into different projects. We do not have the necessary flexibility in constructing and scoping classpaths on a level more granular than the project level, which would be needed to support this functionality.

2. The solution will not allow a single component to span more than one project. Within that project, we will have fairly broad flexibility to specify which resources map to which components. Each component within a project must have its own source folder, but a component may contain more than one source folder. Each source folder may be contained by at most one component. Components may reference dependent components in other projects (so a Web Application may reference a Web Library outside of the project that contains the Web Application).

3. The solution will not allow more than one server target per component (and really per-project) at a time. The ability to switch this server target (via some action or property setting) will continue to be possible. Users that need the capability to develop for multiple server targets will need to manually switch and test as necessary.

4. Each component in a project may have its own output folder structure automatically constructed for it. The output structure will match the J2EE specification output structure required for the component type (for J2EE modules). A new builder will handle this responsibility and work cooperatively with the Java builder to construct a deployable, on-disk representation of the module structure. The reference implementation will follow this pattern, but hooks will be made available to vary this behavior. The necessity for this on-disk structure to match a J2EE-compliant layout is motivated by the requirement to have in-workbench testing, so that users will not have to deal with a deployer actually constructing a deployable module and shipping it off to a server to test their code. This approach is consistent with existing Ant-based approaches and Application Servers which can run in a "debug" mode on disk. Our value-add will be greater automation and integration with the workbench -- particularly for incremental based support. The specialized module builder would not be necessary if the source was already in the appropriate J2EE specification compliant structure. The default creation will still encourage a single module per project, which conforms to the correct J2EE structure.

5. Components will be described using a simple XML format, and each project will contain one .wtpmodules file that will describe all of the components for that project. The level of tooling to help users create these files is yet to be determined for WTP M4. This would be a great area for other interested developers to suggest and provide tooling (e.g. a Wizard or Editor) to create these files from existing structures. A schema is provided to make it easier for consumers that want to build their own .wtpmodules by hand to take advantage of the content assist in the XML editor.

top

ComponentCore API: Working with the metamodel

ComponentCore uses a handle based model much like the existing Platform Resource model. The ComponentCore facade is not tied to any project, and the handles that it returns may or may not exist. The complexity of managing the underlying EMF model is handled under the cover for users.

Figure 2: The ComponentCore API

top