001/* A base interface for transformers.
002
003 Copyright (c) 2003-2013 The University of Maryland.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF MARYLAND BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF MARYLAND HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF MARYLAND SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 MARYLAND HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 */
025package ptolemy.graph.analysis.analyzer;
026
027///////////////////////////////////////////////////////////////////
028//// Transformer
029
030/**
031 A base interface for transformers. Transformers are graph analyzers which
032 transform a graph into another graph and they provide a bilateral way to
033 retrieve the original elements of the graph from the new (transformed) ones
034 and vice versa. If only unilateral relation is being considered,
035 this can be communicated to the client through the {@link #hasBackwardMapping()}
036 and {@link #hasForwardMapping()} methods.
037 <p>
038 @since Ptolemy II 4.0
039 @Pt.ProposedRating Red (shahrooz)
040 @Pt.AcceptedRating Red (ssb)
041 @author Shahrooz Shahparnia, Shuvra S. Bhattacharyya
042 @version $Id$
043 */
044public interface Transformer extends GraphAnalyzer {
045    ///////////////////////////////////////////////////////////////////
046    ////                         public methods                    ////
047
048    /** Specify if this transformer has a mapping from the transformed
049     *  version to the original version or not.
050     *
051     *  @return True  if the implementation of the transformer supports backward
052     *  mapping.
053     */
054    public boolean hasBackwardMapping();
055
056    /** Specify if this transformer has a mapping from the original
057     *  version to the transformed version or not.
058     *
059     *  @return True if the implementation of the transformer supports forward
060     *  mapping.
061     */
062    public boolean hasForwardMapping();
063
064    /** Return the original version of given object in the transformed graph.
065     *  The method should be defined in implementing classes to return the
066     *  original version of the given object. The transformed objects and a
067     *  mapping between the original and the transformed objects are
068     *  created during the transformation process in a specific algorithm
069     *  (strategy).
070     *
071     *  @param transformedObject The given object in the transformed graph.
072     *  @return Return the original version the given object.
073     */
074    public Object originalVersionOf(Object transformedObject);
075
076    /** Return the transformed version of a given object in the original graph.
077     *  The method should be defined in implementing classes to return the
078     *  transformed version of the given object. The transformed objects and a
079     *  mapping between the original and the transformed objects are
080     *  created during the transformation process in a specific algorithm
081     *  (strategy).
082     *
083     *  @param originalObject The given object in the original graph.
084     *  @return Return the transformed version of the given object.
085     */
086    public Object transformedVersionOf(Object originalObject);
087}