001/* Interface for objects that can be configured by reading a file.
002
003 Copyright (c) 1997-2013 The Regents of the University of California.
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 CALIFORNIA 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 CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA 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 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026
027 */
028package ptolemy.kernel.util;
029
030import java.net.URL;
031
032///////////////////////////////////////////////////////////////////
033//// Configurable
034
035/**
036 Objects that can be configured by reading a file or configuration information
037 given as text, typically in XML format, should implement this interface.
038 This enables a user of a component to recognize that such file-based
039 configuration is possible, and permits configuration to be specified
040 via the MoML configure element.
041 For example, a plotter actor implements this interface to
042 allow the visual appearance of the plot to be set using PlotML.
043 An icon for an actor implements this interface to allow
044 the actor-specific visual features of the icon to be
045 specified using graphics markup.
046 Additionally, a filter actor could implement this interface to allow
047 the filter specification to be given using markup.
048 <p>
049 This interface can also be used for actors which load configuration
050 information from non-XML formats, such as GIF images or binary lookup tables.
051 The <i>source</i> argument of the configure() method simply points
052 to such a file.
053 <p>
054 This interface is designed to be reversible, so that an object can also
055 provide enough information to reconstruct its current configuration.
056 This mechanism is used when writing MoML from instantiated objects, although
057 it could also be used to write a description of the object in other forms.
058 In order for this to work properly calling the configure() method on
059 any object of the same type, given the data returned by the getConfigureSource() and
060 getConfigureText() methods should result in an object that resemble the
061 first as closely as possible.
062
063 @author Edward A. Lee, Steve Neuendorffer
064 @version $Id$
065 @since Ptolemy II 1.0
066 @Pt.ProposedRating Green (neuendor)
067 @Pt.AcceptedRating Green (bart)
068 @see ptolemy.actor.CompositeActor
069 @see ptolemy.actor.AtomicActor
070 */
071public interface Configurable {
072    ///////////////////////////////////////////////////////////////////
073    ////                         public methods                    ////
074
075    /** Configure the object with data from the specified input source
076     *  (a URL) and/or textual data.  The object should interpret the
077     *  source first, if it is specified, followed by the literal text,
078     *  if that is specified.  The new configuration should usually
079     *  override any old configuration wherever possible, in order to
080     *  ensure that the current state can be successfully retrieved.
081     *  <p>
082     *  This method is defined to throw a very general exception to allow
083     *  classes that implement the interface to use whatever exceptions
084     *  are appropriate.
085     *  @param base The base relative to which references within the input
086     *   are found, or null if this is not known, or there is none.
087     *  @param source The input source, which specifies a URL, or null
088     *   if none.
089     *  @param text Configuration information given as text, or null if
090     *   none.
091     *  @exception Exception If something goes wrong.
092     */
093    public void configure(URL base, String source, String text)
094            throws Exception;
095
096    /** Return the input source that was specified the last time the configure
097     *  method was called.
098     *  @return The string representation of the input URL, or null if the
099     *  no source has been used to configure this object, or null if no
100     *  external source need be used to configure this object.
101     */
102    public String getConfigureSource();
103
104    /** Return the text string that represents the current configuration of
105     *  this object.  Note that any configuration that was previously
106     *  specified using the source attribute need not be represented here
107     *  as well.
108     *  @return A configuration string, or null if no configuration
109     *  has been used to configure this object, or null if no
110     *  configuration string need be used to configure this object.
111     */
112    public String getConfigureText();
113}