FileDocCategorySizeDatePackage
Name.javaAPI DocGlassfish v2 API12329Fri May 04 22:33:16 BST 2007com.sun.enterprise.admin.common

Name

public final class Name extends Object implements Serializable
A Class to represent a name in the namespace. The name follows the syntactical rules defined in BNF. This class is made Serializable as it is very easily done and potentially the Names can be transmitted over wire between client and server processes.

Serialization is not mandatory, even if a Name is to be shared between remote processes, as the String representation of this Class guarantees a full and lossless reproduction. In other words, new Name( name.toString() ).equals( name ) always returns true .

author
Kedar Mhaswade
version
1.0

Fields Summary
public static final long
serialVersionUID
public static final int
kInvalidIndex
private String
mString
private Vector
mNameParts
Constructors Summary
public Name(String nameString)
The only constructor to create an instance of Name. If a Name can be created from given string representation, it is valid and unique in NameSpace. It is to be noted that a Name can represent name of an attribute or it can represent a Notation. e.g. a.b.c represents a Name, whereas a.b.c.* represents a Notation.

The actual parsing technique is transperant to the client of this class.

param
nameString a string representation of name
throws
MalformedNameException if the given string represents an illegal name


                                                                                                                                                                                

        
    
        //ArgChecker.check(nameString != null && nameString.length() > 0,
        //                "null string for name");

        NameParser parser   =       new NameParser();
        parser.parseIt(nameString);
        Iterator iter       =       parser.getParts();
        mNameParts          =       new Vector();

        while (iter.hasNext())
        {
            Object element = iter.next();
            mNameParts.addElement(element);
        }

        mString             =   nameString;
    
Methods Summary
private java.lang.StringcreatePartialNameString(int beginIndex, int endIndex)

        boolean isInputValid = (beginIndex <= endIndex) &&
                               (endIndex < mNameParts.size()) &&
                               (beginIndex >= 0);
        //ArgChecker.check(isInputValid, "indices are invalid");
        StringBuffer nameBuffer =  new StringBuffer();
        for(int i = beginIndex ; i < endIndex ; i++)
        {
            String aPart = (String)mNameParts.elementAt(i);
            nameBuffer.append(aPart);
            if(i < endIndex - 1)
            {
                nameBuffer.append(Tokens.kDelimiterChar);
            }
        }

        return ( nameBuffer.toString() );
    
public booleanequals(java.lang.Object other)
Checks if the given Object is same as this name. It returns true if and only if the argument is non null and represents same character sequence as that in this name. It is guaranteed that two objects that are equal in this way, will always return equal Strings when toString() is called on them.

param
other the object that this name is to be compared with
return
true if the objects are equal, false otherwise.

        boolean isSame      =   false;

        if (other instanceof Name)
        {
            Name otherName = (Name) other;
            if (this.mString.equals(otherName.mString))
            {
                isSame = true;
            }
        }
        return ( isSame );
    
public intgetIndex()
Returns the index beginning at 0 for a Name that is Indexed. It returns Name.kInvalidIndex for a name i.e. not indexed. (e.g. a.b.c or a.b[0].c, as none of these is indexed). In general, index of an indexed name a.b.c[n] is n. Calling methods have to compare the return value with Name.kInvalidIndex

        int         index       =       kInvalidIndex;
        String      indexString =       null;
        int         startPos, endPos;

        if (isIndexed())
        {
            /*
                Note that a[3].b[7].c.d[4] has an index of 4 and that's why
                we have to taken last index of '[' and ']'. If the name parses
                correct, then the string between last '[' and last ']' is
                bound to be the index of this name.
            */
            startPos    = mString.lastIndexOf(Tokens.kSubScriptBeginnerChar);
            endPos      = mString.lastIndexOf(Tokens.kSubScriptEnderChar);

            //Assert.assert(endPos > startPos, "this should not be indexed!");

            indexString     =       mString.substring(startPos + 1, endPos);
            try
            {
                index   =   Integer.parseInt(indexString);
            }
            catch(NumberFormatException e)
            {
                //ExceptionUtil.ignoreException(e); // this should NEVER happen
            }
        }
        return index;
    
public com.sun.enterprise.admin.common.NamegetNamePart(int partNum)
Returns a Name instance that represents mth part of Name such that, 0 <= m <= n, where n is the number of delimiters (excludig escaped ones)in the string. 0 is applied for the first part.

e.g. For a name "abc.xy.c[5].d",

  • name-part with partNum = 0 is "abc".
  • name-part with partNum = 1 is "xy".
  • name-part with partNum = 2 is "c[5]" and so on.

    if there are no delimiters, then this name itself is returned.

    param
    partNum is an integer denoting the name-part.
    return
    instance of Name that represents nth name-part.

            Name    namePart            =       null;
            String namePartString       =       null;
            int lowerLimit              =       -1;                    //lower limit on index
            int upperLimit              =       mNameParts.size();     //upper limit on index
    
            //ArgChecker.check(partNum, lowerLimit, upperLimit, "number is invalid");
    
            namePartString              =   (String)mNameParts.elementAt(partNum);
    
            try
            {
                namePart                =   new Name(namePartString);
            }
            catch(Exception e)
            {
                //ExceptionUtil.ignoreException(e); // this is actually assertion
            }
            return namePart;
        
  • public intgetNumParts()
    Returns the number of name-parts in this name. A valid name contains at least one name-part, in which case it is this name itself. Every name-part is delimited by Tokens.kDelimiterChar.

    return
    number of name-parts in this name

            return ( mNameParts.size() );
        
    public com.sun.enterprise.admin.common.NamegetParent()
    Returns the Parent Name of this Name. This method is particularly useful in determining location of this Name in hierarchy of Names. Following are the rules applied to determine parent of a Name:
  • a.b.c is always parent of a.b.c.d
  • a.b.c is always parent of a.b.c[n], where n is any valid index
  • a.b.c is always parent of a.b.c.*
  • a.b.c[n] is always the parent of a.b.c[n].d
  • null is always the parent of any string that does not contain any delimiter.

    return
    the Name that represents Parent of this Name

            Name parentName     =       null;
    
            //Assert.assert(! mNameParts.isEmpty(), "Vector of name-parts can't be empty");
    
            int size            =   mNameParts.size();
    
            if(size > 1)
            {
                String nameSubstring = createPartialNameString(0, size - 1);
                try
                {
                    parentName = new Name(nameSubstring);
                }
                catch(MalformedNameException e)
                {
                    //ExceptionUtil.ignoreException(e);
                    //this is actually assertion and should never happen
                }
            }
            return ( parentName );
        
  • public inthashCode()
    Instances of this class can be used as keys in a Hashtable. Since the equals() method is overridden by this class, it is necessary that hashCode() is also overridden, to guarantee that equal instances of this class guarantee to produce equal hashcodes.

    see
    java.lang.Object#hashCode()
    return
    integer representing hashcode for this Name

            return ( mString.length() * 2 + 1 );
        
    public booleanisIndexed()
    A method to determine whether this Name represents an Indexed Name. An Indexed name represents a collection of other Names. Each indexed Name can refer to other Names using different values for the index. An example of an Indexed Name is a.b.c[10]. Note that a.b[0].c is not an Indexed Name. An Indexed Name is different than Name of an Attribute that has multiple values. e.g. a.b.c can have 3 values, none of which can be independently referred to as e.g. a.b.c[1].

    return
    true if this Name represents an Indexed Name, false otherwise

            boolean indexed             =       false;
    
            /* It is already made sure that the length will be greater than zero */
    
            if(mString.charAt(mString.length() - 1) == Tokens.kSubScriptEnderChar)
            {
                indexed     =   true;
            }
    
            return ( indexed );
        
    public java.lang.StringtoString()
    Returns a string that represents this name. Guarantees to return non null String.

    return
    String representing the name

            return ( mString );