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.

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().

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:

CopyC#

public void setFoo(Bar bar)
public Bar getFoo()

CopyC#

public Bar projectFoo(Bar bar);
public Bar revertFoo(Bar bar);

CopyC#

public void setFoo(Bar bar) {
  getViewedFeature().setFoo(getContext().revertFoo(bar));
}

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

CopyC#

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.

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.

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.

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.

Original BioJava version by Thomas Down and Matthew Pocock. Port to C# by Doug Swisher.