STP Core Overview Documentation

STP Core Infrastructure API [Index]

The STP Core Infrastructure layer provides standard management of the EMF Resources which contain model elements. These resources are shared appropriately and reference counted as necessary to prevent loading the same resource into memory multiple times. This ensures that various components in the workbench (e.g. an editor and a view) are rendering the same model and that each reflects the changes of the other.

Design Requirements [Top]
  • Provide a consistent mechanism for managing groups of EMF Resources as a single cohesive unit that can be loaded, read from, written to, and saved or discarded as a single unit.
  • Provide a mechanism to create, edit, and delete individual EMF resources from the set
  • Provide a foolproof mechanism for tracking the usage of each set of EMF resources in order to efficiently load or unload them.
  • Provide a complete but simple API for acquiring a group of EMF resources for a given domain, saving that unit or discarding the changes. The acquisition method should allow clients to load one or more of the resources as read-only.
  • Provide a mechanism for Users to respond to warnings, error, or requests for information in a seamless way (which is also not dependent on UI constructs).
  • Provide a mechanisms to programmatically respond to exceptions or errors encountered during the operation of the set of EMF resources (e.g. save failed, read-only resource, etc).
  • Provide a listener model for clients to track actions around the set of resources including (1) adding a resource, (2) removing a resource, (3) loading a resource, (4) unloading a resource, (5) when resources are about to change [saves] and (6) when a resource has changed
  • Provide an integration story for the standard Eclipse Undoable commands
  • Provide an integration story for the ValidateEdit framework (ResourceStateInputProvider, ResourceStateValidator)
  • Provide a smooth mechanism for getting back to the set of resources from any given model element (perhaps an Adapter pattern?).
Use Cases [Top]

Acquiring an IEditModelScribbler

 
// a code heavy API approach
// The IScribblerDomain describes the resources
//  that the edit model should be interested in.
//  Clients may choose the best way for the creation
//  of these objects. A factory pattern is shown here.
IScribblerDomain scribblerDomain = 
    J2EEScribblerDomainFactory.create(J2EEScribblerDomainType.EJB, project, moduleName);

// Notice the edit model is generic; and is NOT subclassed
IEditModel ejbEditModel = 
    IEditModelFactory.eINSTANCE.getEditModel(project, scribblerDomain.getEditModelLablel());

// The scribbler becomes the focal point for 
//  save(), revert(), discard(), etc; it also
//  provides an easier way to manage ref counts
//  (so no more access(), release() calls!
IEditModelScribbler scribbler = 
    ejbEditModel.createScribbler(scribblerDomain, readOnly);

...
try {
    scribbler.close();
} catch(EditModelException eme) { 
    // handle exception
} 
			

Acquiring an IEditModelScribbler

  
// a code light API approach
IScribblerDomain scribblerDomain = 
    J2EEScribblerDomainFactory(J2EEScribblerDomainType.EJB, moduleName);

// The IEditModelFactory can create the edit model under the covers
IEditModelScribbler scribbler = 
    IEditModelFactory.eINSTANCE.createScribblerForRead(project, scribblerDomain);

...
try {
    scribbler.close(force);
} catch(EditModelException eme) { 
    // handle exception 
}
			

Acquiring an IEditModelScribbler

  

// a code light API approach (different IScribblerDomain)
List descriptorsList = new ArrayList();

// collect descriptors of interest
...

// IResourceDescriptor describes the resources
//  it can specify a default location and an
//  exact location
IResourceDescriptor[] descriptors = null;
descriptorsList.toArray(
    (descriptors = new IResourceDescriptor [descriptorsList.size()])
     );

IScribblerDomain scribblerDomain = 
    IScribblerDomain.create(descriptors);
IEditModelScribbler scribbler = 
    IEditModelFactory.eINSTANCE.createScribblerForRead(project, scribblerDomain);

...
try {
    scribbler.close();
} catch(EditModelException eme) { 
    // handle exception
} 
			

Saving modifications from an Editor

  
try {
    scribbler.save(true);
} catch(EditModelException eme) { 
    // handle exception
} 
			

Saving modifications from an Operation

  
try {
    scribbler.save(false);
} catch(EditModelException eme) { 
    // handle exception
} 
			

Creating an IScribblerDomain

  

// Clients have full control over how their IScribblerDomains
// are created; clients may choose to use a Factory Pattern
IScribblerDomain technologyDomainForProject =     
    MyCustomScribblerDomainFactory.createDomain(aProject);


public class SimpleScribblerDomain implements IScribblerDomain { private final IProject project; private final Set descriptors = new HashSet(); public SimpleScribblerDomain (IProject aProject) { project = aProject; descriptors.add( new EclipseResourceDescriptor("/custom/myfile.xmi") ); } public IResourceDescriptor[] getResourceDescriptors() { IResourceDescriptor[] storage = null; synchronized(descriptors) { storage = new IResourceDescriptor[descriptors.zize()]; storage = (IResourceDescriptor[]) descriptors.toArray(storage); } return storage; } public void add(IResourceDescriptor aResourceDescriptor) { synchronized(descriptors) { descriptors.add(aResourceDescriptor); } } public boolean isContained(IResourceDescriptor aResourceDescriptor) { return descriptors.contains(aResourceDescriptor); } public boolean isContained(Resource aResource) { return isContained(new SimpleDescriptor(aResource)); } public String getEditModelLabel() { return project.getName()+".custom"; } }
IScribblerDomain simpleDomain = new SimpleScribblerDomain(project); IFile file = project.getFile("somefile.xmi"); resourceDescriptor = new EclipseResourceDescriptor(file); simpleDomain.add(resourceDescriptor); IEditModelScribbler scribbler = IEditModel.eINSTANCE.createScribblerForWrite(project, simpleDomain);

Loading an existing Resource

  
scribbler.getResource(theURI);
			

Creating a Resource

  
IResourceDescriptor descriptor = 
    new EclipseResourceDescriptor(anIFile);
Resource resource = scribbler.createResource(descriptor); 
			

This documentation is maintained by Michael D. Elder (mdelder{at}us.ibm.com). Questions or requests for clarifications should be made to the STP Developer mailing list (stp-dev@eclipse.org). See http://www.eclipse.org/mail/index_all.php for details on how to sign up.

Copyright (c) 2006 IBM Corporation. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html

[Index] [Top]