Name


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package com.sun.enterprise.admin.common;
25  
26  import java.io.Serializable  ;
27  import java.util.Vector  ;
28  import java.util.Iterator  ;
29  
30  /**
31      A Class to represent a name in the namespace. The name follows the
32      syntactical rules defined in BNF. This class is made Serializable as it is
33      very easily done and potentially the Names can be transmitted over wire
34      between client and server processes.
35      <p>
36      Serialization is not mandatory, even if
37      a Name is to be shared between remote processes, as the String representation
38      of this Class guarantees a full and lossless reproduction. In other words,
39      new Name( name.toString() ).equals( name ) always returns <strong> true
40      </strong>.
41      @author Kedar Mhaswade
42      @version 1.0
43  */
44  
45  public final class Name implements Serializable  
46  {
47      /* javac 1.3 generated serialVersionUID */
48      public static final long serialVersionUID                   = 4479037048166596417L;
49      public static final     int         kInvalidIndex           = -1;
50  
51      private                 String        mString                 = null;
52      /*
53          A vector of strings of name-parts. Note that if there are
54          n delimiters, (n+1) are stored into this vector. In other words, for
55          a valid name, this vector contains at least one element.
56      */
57      private                 Vector        mNameParts              = null;
58  
59      /**
60          The only constructor to create an instance of Name. If a Name can
61          be created from given string representation, it is valid and unique
62          in NameSpace. It is to be noted that a Name can represent name of an
63          attribute or it can represent a Notation.
64          e.g. a.b.c represents a Name, whereas a.b.c.* represents a Notation.
65          <p>
66          The actual parsing technique is transperant to the client of this class.
67          <p>
68          @param nameString a string representation of name
69          @throws MalformedNameException if the given string represents an illegal
70              name
71      */
72  
73      public Name(String   nameString) throws MalformedNameException
74      {
75          //ArgChecker.check(nameString != null && nameString.length() > 0,
76          //                "null string for name");
77  
78          NameParser parser   =       new NameParser();
79          parser.parseIt(nameString);
80          Iterator   iter       =       parser.getParts();
81          mNameParts          =       new Vector  ();
82  
83          while (iter.hasNext())
84          {
85              Object   element = iter.next();
86              mNameParts.addElement(element);
87          }
88  
89          mString             =   nameString;
90      }
91      /**
92        Returns a Name instance that represents mth part of Name such that,
93        0 <= m <= n,
94        where n is the number of delimiters (excludig escaped ones)in the string.
95        0 is applied for the first part.
96        <p>
97        e.g. For a name "abc.xy.c[5].d",
98        <li>
99        name-part with partNum = 0 is "abc".
100       <li>
101       name-part with partNum = 1 is "xy".
102       <li>
103       name-part with partNum = 2 is "c[5]" and so on.
104       <p>
105       if there are no delimiters, then this name itself is returned.
106       <p>
107       @param    partNum is an integer denoting the name-part.
108       @return   instance of Name that represents nth name-part.
109     */
110 
111     public Name getNamePart(int partNum)
112     {
113         Name    namePart            =       null;
114         String   namePartString       =       null;
115         int lowerLimit              =       -1;                    //lower limit on index
116         int upperLimit              =       mNameParts.size();     //upper limit on index
117 
118         //ArgChecker.check(partNum, lowerLimit, upperLimit, "number is invalid");
119 
120         namePartString              =   (String  )mNameParts.elementAt(partNum);
121 
122         try
123         {
124             namePart                =   new Name(namePartString);
125         }
126         catch(Exception   e)
127         {
128             //ExceptionUtil.ignoreException(e); // this is actually assertion
129         }
130         return namePart;
131     }
132 
133 
134     /**
135         Returns the Parent Name of this Name. This method is particularly
136         useful in determining location of this Name in hierarchy of Names.
137         Following are the rules applied to determine parent of a Name:
138         <li>
139             a.b.c is always parent of a.b.c.d
140         <li>
141             a.b.c is always parent of a.b.c[n], where n is any valid index
142         <li>
143             a.b.c is always parent of a.b.c.*
144         <li>
145             a.b.c[n] is always the parent of a.b.c[n].d
146         <li>
147             null is always the parent of any string that does not contain
148                 any delimiter.
149 
150         @return the Name that represents Parent of this Name
151     */
152 
153     public Name getParent()
154     {
155         Name parentName     =       null;
156 
157         //Assert.assert(! mNameParts.isEmpty(), "Vector of name-parts can't be empty");
158 
159         int size            =   mNameParts.size();
160 
161         if(size > 1)
162         {
163             String   nameSubstring = createPartialNameString(0, size - 1);
164             try
165             {
166                 parentName = new Name(nameSubstring);
167             }
168             catch(MalformedNameException e)
169             {
170                 //ExceptionUtil.ignoreException(e);
171                 //this is actually assertion and should never happen
172             }
173         }
174         return ( parentName );
175     }
176 
177 
178     /**
179         Returns the number of name-parts in this name. A valid name contains
180         at least one name-part, in which case it is this name itself. Every
181         name-part is delimited by Tokens.kDelimiterChar.
182 
183         @return number of name-parts in this name
184     */
185 
186     public int getNumParts()
187     {
188         return ( mNameParts.size() );
189     }
190 
191     /**
192         A method to determine whether this Name represents an Indexed Name. An
193         Indexed name represents a collection of other Names. Each indexed
194         Name can refer to other Names using different values for the index.
195         An example of an Indexed Name is a.b.c[10].
196         Note that a.b[0].c is <it> not </it> an Indexed Name.
197         An Indexed Name is different than Name of an Attribute that has multiple
198         values. e.g. a.b.c can have 3 values, none of which can be independently
199         referred to as e.g. a.b.c[1].
200 
201         @return true if this Name represents an Indexed Name, false otherwise
202     */
203 
204     public boolean isIndexed()
205     {
206         boolean indexed             =       false;
207 
208         /* It is already made sure that the length will be greater than zero */
209 
210         if(mString.charAt(mString.length() - 1) == Tokens.kSubScriptEnderChar)
211         {
212             indexed     =   true;
213         }
214 
215         return ( indexed );
216     }
217 
218 
219     /**
220         Returns the index beginning at 0 for a Name that is Indexed. It returns
221         Name.kInvalidIndex for a name i.e. not indexed.
222         (e.g. a.b.c or a.b[0].c, as none of these is indexed).
223         In general, index of an indexed name a.b.c[n] is n.
224         Calling methods have to compare the return value with Name.kInvalidIndex
225     */
226 
227     public int getIndex()
228     {
229         int         index       =       kInvalidIndex;
230         String        indexString =       null;
231         int         startPos, endPos;
232 
233         if (isIndexed())
234         {
235             /*
236                 Note that a[3].b[7].c.d[4] has an index of 4 and that's why
237                 we have to taken last index of '[' and ']'. If the name parses
238                 correct, then the string between last '[' and last ']' is
239                 bound to be the index of this name.
240             */
241             startPos    = mString.lastIndexOf(Tokens.kSubScriptBeginnerChar);
242             endPos      = mString.lastIndexOf(Tokens.kSubScriptEnderChar);
243 
244             //Assert.assert(endPos > startPos, "this should not be indexed!");
245 
246             indexString     =       mString.substring(startPos + 1, endPos);
247             try
248             {
249                 index   =   Integer.parseInt(indexString);
250             }
251             catch(NumberFormatException   e)
252             {
253                 //ExceptionUtil.ignoreException(e); // this should NEVER happen
254             }
255         }
256         return index;
257     }
258 
259 
260     /**
261         Returns a string that represents this name. Guarantees to return
262         non null String.
263 
264         @return String representing the name
265     */
266 
267     public String   toString()
268     {
269         return ( mString );
270     }
271 
272 
273     /**
274         Checks if the given Object is same as this name. It returns true if
275         and only if the argument is non null and represents same character
276         sequence as that in this name. It is guaranteed that two objects that
277         are equal in this way, will always return equal Strings when toString()
278         is called on them.
279 
280         @param other the object that this name is to be compared with
281         @return true if the objects are equal, false otherwise.
282     */
283 
284     public boolean equals(Object   other)
285     {
286         boolean isSame      =   false;
287 
288         if (other instanceof Name)
289         {
290             Name otherName = (Name) other;
291             if (this.mString.equals(otherName.mString))
292             {
293                 isSame = true;
294             }
295         }
296         return ( isSame );
297     }
298 
299 
300     /**
301         Instances of this class can be used as keys in a Hashtable. Since the
302         equals() method is overridden by this class, it is necessary that
303         hashCode() is also overridden, to guarantee that equal instances of
304         this class guarantee to produce equal hashcodes.
305 
306         @see java.lang.Object#hashCode()
307         @return integer representing hashcode for this Name
308     */
309 
310     public int hashCode()
311     {
312         return ( mString.length() * 2 + 1 );
313     }
314 
315     private String   createPartialNameString(int beginIndex, int endIndex)
316     {
317         boolean isInputValid = (beginIndex <= endIndex) &&
318                                (endIndex < mNameParts.size()) &&
319                                (beginIndex >= 0);
320         //ArgChecker.check(isInputValid, "indices are invalid");
321         StringBuffer   nameBuffer =  new StringBuffer  ();
322         for(int i = beginIndex ; i < endIndex ; i++)
323         {
324             String   aPart = (String  )mNameParts.elementAt(i);
325             nameBuffer.append(aPart);
326             if(i < endIndex - 1)
327             {
328                 nameBuffer.append(Tokens.kDelimiterChar);
329             }
330         }
331 
332         return ( nameBuffer.toString() );
333     }
334 
335 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags