Package 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.

    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.
    Since:
    1.4
    Author:
    Thomas Down, Matthew Pocock

    • 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

      • 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

      • 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

      • 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