org.biojava.bio.seq.projection
Interface ProjectionContext

All Known Implementing Classes:
ReparentContext, SimpleGappedSequence.GappedContext, SubSequence.SubProjectedFeatureContext, TranslateFlipContext

public interface ProjectionContext

Interface that defines the projection between original features and projected features.

Note: Implementing this interface is not trivial. It is assumed that if you are implementing this, you are a power user or developer. All method documentation is aimed at those groups, not users.

Core projection methods

This interface directly specifies a core set of methods that a ProjectionContext implementation must provide. These are needed to allow ProjectedFeatureHolder to connect to the context and for projected features to be implemented on top of the context.

All of these methods are implemented by @link ReparentContext, and it would be unwise to try to implement them again independently, but it's a free world and this is, after all, an interface. Some of the methods have contracts that are a little tricky to implement without some thought.

The methods projectFeature() and revertFeature() should be used as your exclusive means for converting features between the two views. If you have some utility method that produces projections, it /must/ be exclusively invoked from projectFeature(). Likewise, although it is tempting to cast the projected feature to Projection, and then to call getProjectedFeature(), this will break the encapsulation of the context. The only method that should do this cast is revertFeature().

Extra projection methods

Projection methods are used by the projection engine to map projected and unprojected feature properties. They are not declared directly in this interface, but should be supplied by implementations. They will be picked up by the projection engine using introspection, and connected to projected feature instances by run-time code generation.

So that the projection methods can be found, they should all follow the same template. If a feature interface has a property foo of type Bar, then the feature interface will have the two methods:

 public void setFoo(Bar bar)
 public Bar getFoo()
 
The projection engine will be looking for a pair of methods in the context named: public Bar projectFoo(Bar bar); public Bar revertFoo(Bar bar); If these methods are found, then the projected feature will have get/set methods that resemble:
 public void setFoo(Bar bar) {
   getViewedFeature().setFoo(getContext().revertFoo(bar));
 }

 public Bar getFoo() {
   return getContext().projectFoo(getViewedFeature().getFoo());
 }
 
If these methods are not found, then the projected feature will have get/set methods that resembl:
 public void setFoo(Bar bar) {
   getViewedFeature().setFoo(bar);
 }

 public Bar getFoo() {
   return getContext().getViewedFeature().getFoo();
 }
 

Only those methods defined by the interface of the unprojected feature will be mapped accross. So, if the context provides projectors for the strand property but the feature is not a stranded feature, it's projection will not have a strand property.

Since:
1.4
Author:
Thomas Down, Matthew Pocock
For general use:
You should probably not be implementing these yourself. Use the standard factory methods in SequenceTools to create new sequences that are altered views of other sequences.
For advanced users:
You will probably want to instantiate @link ReparentContext or @link TranslateFlipContext to achieve the most commonly needed transformations. If you do have to implement this, extend one of these two classes.
For developers:
Consider extending @link ReparentContext or @link TranslateFlipContex. They do a lot of complex work for you.

When projecting an original location origLoc to your new location yourLoc, be sure to make sure the decorations match. The easiest way to do this is return origLoc.newInstance(yourLoc).

Every ProjectionContext implementation must be a public or package-private class. This is because ProjectionEngine wires method calls from the projected features back into the context. These methods are not necessarily defined by the context interface (if they are project/revert pairs), so the class itself must be directly accessible. The ProjectionEngine creates accessory classes in the same package as the context it is using.

Method Summary
 void addChangeListener(Feature projFeat, ChangeListener cl, ChangeType ct)
          Add a ChangeListener to a projected feature.
 Feature createFeature(Feature.Template projTempl)
          Create a projected feature with properties matching the template.
 Feature createFeature(Feature projParent, Feature.Template projTempl)
          Create a new projected feature.
 FeatureHolder getParent(Feature projFeat)
           
 Sequence getSequence(Feature projFeat)
          Get the sequence for a feature.
 FeatureHolder getUnprojectedFeatures()
          Get the features before projection.
 FeatureHolder projectChildFeatures(Feature feature, FeatureHolder parent)
          Project all features that are children of feature so that they become children of parent.
 Feature projectFeature(Feature feat)
          Project a single feature.
 FeatureHolder projectFeatures(FeatureHolder features)
          Project all of the features in a FeatureHolder.
 FeatureFilter projectFilter(FeatureFilter filt)
          Transform a filter on unprojected features so that it applies to projected features.
 void removeChangeListener(Feature projFeat, ChangeListener cl, ChangeType ct)
          Remove a ChangeListener from a projected feature.
 void removeFeature(Feature dyingChild)
          Remove the dying child.
 void removeFeature(Feature projParent, Feature dyingChild)
          Remove the dying child.
 Feature revertFeature(Feature projFeat)
          Unproject a feature.
 FeatureFilter revertFilter(FeatureFilter filt)
          Transform a filter on projected features so that it applies to unprojected features.
 

Method Detail

getUnprojectedFeatures

FeatureHolder getUnprojectedFeatures()
Get the features before projection.

If you are projecting all the features in some feature holder, that is what this method should return.

Returns:
the features before projection

getParent

FeatureHolder getParent(Feature projFeat)

getSequence

Sequence getSequence(Feature projFeat)
Get the sequence for a feature.

This will be the return value of projFeat.getParent().

Parameters:
projFeat - the projected Feature
Returns:
the Sequence of the Feature

projectFeature

Feature projectFeature(Feature feat)
Project a single feature.

Parameters:
feat - the Feature to project
Returns:
a Feature representing feat after being transformed by this context

projectFeatures

FeatureHolder projectFeatures(FeatureHolder features)
Project all of the features in a FeatureHolder.

Warning: The results of calling this method for features that are not in getUnprojectedFeatures() is not specified by this API, but it is reasonable to assume that bad things will happen.

Parameters:
features - the FeatureHolder containing the features to project
Returns:
a FeatureHolder containing all the features projected

revertFeature

Feature revertFeature(Feature projFeat)
Unproject a feature.

This is the inverse opperation to @link projectFeature().

Note: The result of calling this method for a feature that is not projected through this context is not specified by this API, but it is reasonable to assume that bad things will happen.

Parameters:
projFeat - the Feature to un-project
Returns:
the unprojected feature

projectFilter

FeatureFilter projectFilter(FeatureFilter filt)
Transform a filter on unprojected features so that it applies to projected features.

Parameters:
filt - the FeatureFilter to transform
Returns:
the transformed FeatureFilter

revertFilter

FeatureFilter revertFilter(FeatureFilter filt)
Transform a filter on projected features so that it applies to unprojected features.

Parameters:
filt - the FeatureFilter to transform
Returns:
the transformed FeatureFilter

projectChildFeatures

FeatureHolder projectChildFeatures(Feature feature,
                                   FeatureHolder parent)
Project all features that are children of feature so that they become children of parent.

Parameters:
feature - the Feature to project all children of
parent - the new parent feature holder
Returns:
a FeatureHolder containing projections of all children of feature so that f.getParent() is equal to parent

createFeature

Feature createFeature(Feature.Template projTempl)
                      throws BioException,
                             ChangeVetoException
Create a projected feature with properties matching the template.

You will probably implement this by delegating to the unprojected feature holder. It is imperative that the template properties are unprojected first so that when the newly created feature is projected, the properties match up.

Not every projection context has fully reversible semantics. Use your discression and come up with a reasonable plan that causes least supprise to the user.

Parameters:
projTempl - the Feature.Template to instantiate
Returns:
a new projected Feature matching the template as closely as possible
Throws:
BioException - if there was a problem instantiating the template
ChangeVetoException - if the feature creation was vetoed

removeFeature

void removeFeature(Feature dyingChild)
                   throws BioException,
                          ChangeVetoException
Remove the dying child.

Parameters:
dyingChild - a projected feature to remove
Throws:
BioException - if there is an error removing the feature
ChangeVetoException - if the removal of the feature was vetoed

createFeature

Feature createFeature(Feature projParent,
                      Feature.Template projTempl)
                      throws BioException,
                             ChangeVetoException
Create a new projected feature.

See the notes for @link createFeature(Feature.Template) for implementation advice.

Parameters:
projParent - the parent for the newly created feature
projTempl - the Feature.Template specifying the new feature
Returns:
a new ProjectedFeature that is a child of projParent
Throws:
BioException - if there was a problem creating the feature
ChangeVetoException - if the creation of the feature was vetoed

removeFeature

void removeFeature(Feature projParent,
                   Feature dyingChild)
                   throws ChangeVetoException,
                          BioException
Remove the dying child.

Parameters:
projParent - the projected parent Feature
dyingChild - the child Feature to remove
Throws:
ChangeVetoException - if the removal of the feature was vetoed
BioException

addChangeListener

void addChangeListener(Feature projFeat,
                       ChangeListener cl,
                       ChangeType ct)
Add a ChangeListener to a projected feature.

Parameters:
projFeat - the projected Feature to add the listener for
cl - the ChangeListener to add
ct - the ChangeType to register it for

removeChangeListener

void removeChangeListener(Feature projFeat,
                          ChangeListener cl,
                          ChangeType ct)
Remove a ChangeListener from a projected feature.

Parameters:
projFeat - the projected Feature to remove the listener for
cl - the ChangeListener to remove
ct - the ChangeType it is registered for