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