User Guide

The eModeling project is a framework for managing EMF resources through OSGi services. The core framework is split between an API bundle and several component (implementation) bundles. Additional bundles provide enhanced capabilities for object queries, OSGi logging, and JUnit testing. The diagram below depicts the services provided and their inter-dependencies.

ResourceCache

The ResourceCache service maintains a single instance of a ResourceSet. The instance of the ResourceSet is most likely not thread safe so you should not use this service as a cache in a multi-threaded server. It can be quite useful as a cache in a UI where all operations are single threaded.

The implementation of ResourceCache is provided by the org.eclipselabs.emodeling.rs.cache bundle. This implementation requires a reference to a ResourceSetFactory service.

Example usage:

@Component
public class Component
{
  private volatile ResourceCache resourceCache;

  @Activate
  public void activate()
  {
    ResourceSet resourceSet = resourceCache.getResourceSet();
    ...
  }

  @Reference(unbind = "-")
  public void bindResourceCache(ResourceCache resourceCache)
  {
    this.resourceCache = resourceCache;
  }
}

ResourceSetFactory

The ResourceSetFactory service creates a new instance of a ResourceSet on each call. Client code will typically use this service whenever a ResourceSet is needed.

There are two implementations: org.eclipselabs.emodeling.rs.basic and org.eclipselabs.emodeling.rs.mongo. The basic bundle creates an instance of ResourceSetImpl defined by EMF. The mongo bundle creates an instance of MongoResourceSetImpl which is a custom resource set created for better performance when you have a large number of resources.

I recall there were some performance enhancements to ResourceSetImpl so MongoResourceSetImpl may be deprecated in the next version.

Both implementations have an optional 0..n reference to the ResourceSetConfigurator service. You must use caution when your application requires the resource set to be configured by a ResourceSetConfigurator service since the reference is optional, it may be possible to create a ResourceSet before the configurator(s) have been bound to the factory service.

Example usage:

@Component
public class Component
{
  private volatile ResourceSetFactory resourceSetFactory;

  @Activate
  public void activate()
  {
    ResourceSet resourceSet = resourcSetFactory.createResourceSet();
    ...
  }

  @Reference(unbind = "-")
  public void bindResourceSetFactory(ResourceSetFactory resourceSetFactory)
  {
    this.resourceSetFactory = resourceSetFactory;
  }
}

ResourceSetConfigurator

The ResourceSetConfigurator service allows a ResourceSet to be customized during creation. This service called by the factory service before the ResourceSet is returned to the user.

An implementation of ResourceSetConfigurator is provided by the org.eclipselabs.emodeling.rs.handler bundle. This implementation will add URIHandler implementations to the URIConverter of the ResourceSet as well as URI mappings. This implementation has an optional 0..n reference to the UriHandlerProvider and UriMapProvider services.

Users may provide their own implementation of this service and all registered implementations of this interface will be called when a new ResourceSet is created by the factory service.

Users will typically not consume this service.

UriHandlerProvider

The UriHandlerProvider service is implemented by client code (you). This service provides a hook for adding URIHandler instances to a ResourceSet when it is created.

Users will typically not consume this service.

Example implementation:

@Component(service = UriHandlerProvider.class)
public class MyUriHandlerProvider implements UriHandlerProvider
{
  private URIHandler uriHandler;

  public synchronized URIHandler getURIHandler()
  {
    if(uriHandler == null)
      uriHandler = new MyUriHandler();

    return uriHandler;
  }
}

UriMapProvider

The UriMapProvider service provides a hook for adding URI mappings to a ResourceSet when it is created.

The implementation of UriMapProvider is provided by the org.eclipselabs.emodeling.rs.mapping bundle. The implementation provides a single URI mapping as specified by service configuration properties:

• src : source URI
• dest : destination URI

Users need to supply a service configuration using ConfigurationAdmin for each URI mapping needed.

Simple Query

The query (org.eclipselabs.emodeling.query) bundle contains an EMF model for creating simple EMF queries. The typical usage would be returning objects from a data store such as MongoDB.

Logging

The logging (org.eclipselabs.emodeling.log.core) bundle contains an EMF model for storing log entries. The typical usage would be to implement an OSGi LogListener that creates an EMF LogEntry for each OSGi log message. An example can be found in the MongoEMF project where the log data is stored to MongoDB.

Matchers

Two Hamcrest matchers are available for testing object and attribute equality. These matchers are typically used with JUnit testing; however, Hamcrest matchers can be used independent of JUnit.

###EqualToEAttribute

This matcher will test the equality of the specified EAttribute.

Example:

assertThat(eObject1, is(equalToEAttribute(eObjcect1, ModelPackage.Literals.MYOBJECT__MYATTRIBUTE)));

###EqualToEObject

This matcher till test the equality of the specified EObject. It will traverse all EReferences and requires that all references are equal in addition to the attributes.

Example:

assertThat(eObject11, is(equalToEObject(eObject2)));

There may be cases where you do not want to have an EStructuralFeature considered in the test for equality. For those cases, you may specified a set of structural features to exclude from testing.

Example:

Set<EStructuralFeature> excludedFeatures = new HashSet<EStructuralFeature>();
excludedFeatures.add(ModelPackage.Literals.EOBJECT__ESTRUCTURALFEATURE);

assertThat(eObjec1, is(equalToEObject(eObject2, excludedFeatures)));