001/* Interface for objects with a name and a container.
002
003 Copyright (c) 1997-2014 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
030///////////////////////////////////////////////////////////////////
031//// Nameable
032
033/**
034 This is an interface for objects with a name and a container. A simple
035 name is an arbitrary string that identifies the object in the context of
036 its container. In addition, the interface supports a
037 "full name" which in implementation should identify both the container
038 and the individual object. The implementations in the kernel package
039 define the full name of an object to be the full name of its container
040 followed by a period followed by the simple name of the object.
041 Periods and braces are not permitted in the name.
042
043 @author Christopher Hylands, Edward A. Lee
044 @version $Id$
045 @since Ptolemy II 0.2
046 @Pt.ProposedRating Green (eal)
047 @Pt.AcceptedRating Green (johnr)
048 */
049public interface Nameable {
050    ///////////////////////////////////////////////////////////////////
051    ////                         public methods                    ////
052
053    /** Return a description of the object. The general
054     *  form of the description is a space-delimited list of the form
055     *  "className fullName <i>keyword</i> field <i>keyword</i> field ...".
056     *  If any of the items contain spaces, then they must be surrounded
057     *  by braces, as in "{two words}". Return characters or newlines
058     *  may be be used as delimiters as well. The fields are usually
059     *  lists of descriptions of this same form, although different
060     *  forms can be used for different keywords.  The keywords are
061     *  extensible, but the following are in use: links, ports, entities,
062     *  relations, attributes, and inside links, at least.
063     *  @return A description of this object.
064     *  @exception IllegalActionException If there is a problem accessing
065     *  subcomponents of the object.
066     */
067    public String description() throws IllegalActionException;
068
069    /** Return the container.
070     *  @return The container.
071     */
072    public NamedObj getContainer();
073
074    /** Return a name to present to the user.
075     *  @return A name to present to the user.
076     */
077    public String getDisplayName();
078
079    /** Return the full name, which reflects the container object, if there
080     *  is one. For example the implementation in NamedObj concatenates the
081     *  full name of the container objects with the name of the this object,
082     *  separated by periods.
083     *  @return The full name of the object.
084     */
085    public String getFullName();
086
087    /** Return the name of the object.
088     *  @return The name of the object.
089     *  @see #setName(String)
090     */
091    public String getName();
092
093    /** Get the name of this object relative to the specified container.
094     *  If this object is contained directly by the specified container,
095     *  this is just its name, as returned by getName().  If it is deeply
096     *  contained by the specified container, then the relative name is
097     *  <i>x1</i>.<i>x2</i>. ... .<i>name</i>, where <i>x1</i> is directly
098     *  contained by the specified container, <i>x2</i> is contained by
099     *  <i>x1</i>, etc.  If this object is not deeply contained by the
100     *  specified container, then this method returns the full name of
101     *  this object, as returned by getFullName().
102     *  @param relativeTo The object relative to which you want the name.
103     *  @return A string of the form "name2...nameN".
104     *  @exception InvalidStateException If a recursive structure is
105     *   encountered, where this object directly or indirectly contains
106     *   itself. Note that this is a runtime exception so it need not
107     *   be declared explicitly.
108     *  @see #setName(String)
109     */
110    public String getName(NamedObj relativeTo) throws InvalidStateException;
111
112    /** Set or change the name. By convention, if the argument is null,
113     *  the name should be set to an empty string rather than to null.
114     *  @param name The new name.
115     *  @exception IllegalActionException If the name contains a period.
116     *  @exception NameDuplicationException If the container already
117     *   contains an object with this name.
118     *  @see #getName()
119     *  @see #getName(NamedObj)
120     */
121    public void setName(String name)
122            throws IllegalActionException, NameDuplicationException;
123}