CatalogEntry


1   // CatalogEntry.java - Represents Catalog entries
2   
3   /* ====================================================================
4    * The Apache Software License, Version 1.1
5    *
6    * Copyright (c) 2001-2003 The Apache Software Foundation.  All rights
7    * reserved.
8    *
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   *
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   *
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   *
21   * 3. The end-user documentation included with the redistribution,
22   *    if any, must include the following acknowledgment:
23   *       "This product includes software developed by the
24   *        Apache Software Foundation (http://www.apache.org/)."
25   *    Alternately, this acknowledgment may appear in the software itself,
26   *    if and wherever such third-party acknowledgments normally appear.
27   *
28   * 4. The names "Apache" and "Apache Software Foundation" must
29   *    not be used to endorse or promote products derived from this
30   *    software without prior written permission. For written
31   *    permission, please contact apache@apache.org.
32   *
33   * 5. Products derived from this software may not be called "Apache",
34   *    nor may "Apache" appear in their name, without prior written
35   *    permission of the Apache Software Foundation.
36   *
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   *
51   * This software consists of voluntary contributions made by many
52   * individuals on behalf of the Apache Software Foundation.  For more
53   * information on the Apache Software Foundation, please see
54   * <http://www.apache.org/>.
55   */
56  
57  package org.jboss.util.xml.catalog;
58  
59  import java.util.Hashtable  ;
60  import java.util.Vector  ;
61  
62  /**
63   * Represents a Catalog entry.
64   *
65   * <p>Instances of this class represent individual entries
66   * in a Catalog.</p>
67   *
68   * <p>Each catalog entry has a unique name and is associated with
69   * an arbitrary number of arguments (all strings). For example, the
70   * TR9401 catalog entry "PUBLIC" has two arguments, a public identifier
71   * and a system identifier. Each entry has a unique numeric type,
72   * assigned automatically when the entry type is created.</p>
73   *
74   * <p>The number and type of catalog entries is maintained
75   * <em>statically</em>. Catalog classes, or their subclasses, can add
76   * new entry types, but all Catalog objects share the same global pool
77   * of types.</p>
78   *
79   * <p>Initially there are no valid entries.</p>
80   *
81   * @see Catalog
82   *
83   * @author Norman Walsh
84   * <a HREF="mailto:Norman.Walsh@Sun.COM">Norman.Walsh@Sun.COM</a>
85   *
86   * @version 1.0
87   */
88  public class CatalogEntry {
89    /** The nextEntry is the ordinal number of the next entry type. */
90    protected static int nextEntry = 0;
91  
92    /**
93     * The entryTypes vector maps catalog entry names
94     * (e.g., 'BASE' or 'SYSTEM') to their type (1, 2, etc.).
95     * Names are case sensitive.
96     */
97    protected static Hashtable   entryTypes = new Hashtable  ();
98  
99    /** The entryTypes vector maps catalog entry types to the
100       number of arguments they're required to have. */
101   protected static Vector   entryArgs = new Vector  ();
102 
103   /**
104    * Adds a new catalog entry type.
105    *
106    * @param name The name of the catalog entry type. This must be
107    * unique among all types and is case-sensitive. (Adding a duplicate
108    * name effectively replaces the old type with the new type.)
109    * @param numArgs The number of arguments that this entry type
110    * is required to have. There is no provision for variable numbers
111    * of arguments.
112    * @return The type for the new entry.
113    */
114   public static int addEntryType(String   name, int numArgs) {
115     entryTypes.put(name, new Integer  (nextEntry));
116     entryArgs.add(nextEntry, new Integer  (numArgs));
117     nextEntry++;
118 
119     return nextEntry-1;
120   }
121 
122   /**
123    * Lookup an entry type
124    *
125    * @param name The name of the catalog entry type.
126    * @return The type of the catalog entry with the specified name.
127    * @throws InvalidCatalogEntryTypeException if no entry has the
128    * specified name.
129    */
130   public static int getEntryType(String   name)
131     throws CatalogException {
132     if (!entryTypes.containsKey(name)) {
133       throw new CatalogException(CatalogException.INVALID_ENTRY_TYPE);
134     }
135 
136     Integer   iType = (Integer  ) entryTypes.get(name);
137 
138     if (iType == null) {
139       throw new CatalogException(CatalogException.INVALID_ENTRY_TYPE);
140     }
141 
142     return iType.intValue();
143   }
144 
145   /**
146    * Find out how many arguments an entry is required to have.
147    *
148    * @param name The name of the catalog entry type.
149    * @return The number of arguments that entry type is required to have.
150    * @throws InvalidCatalogEntryTypeException if no entry has the
151    * specified name.
152    */
153   public static int getEntryArgCount(String   name)
154     throws CatalogException {
155     return getEntryArgCount(getEntryType(name));
156   }
157 
158   /**
159    * Find out how many arguments an entry is required to have.
160    *
161    * @param type A valid catalog entry type.
162    * @return The number of arguments that entry type is required to have.
163    * @throws InvalidCatalogEntryTypeException if the type is invalid.
164    */
165   public static int getEntryArgCount(int type)
166     throws CatalogException {
167     try {
168       Integer   iArgs = (Integer  ) entryArgs.get(type);
169       return iArgs.intValue();
170     } catch (ArrayIndexOutOfBoundsException   e) {
171       throw new CatalogException(CatalogException.INVALID_ENTRY_TYPE);
172     }
173   }
174 
175   /** The entry type of this entry */
176   protected int entryType = 0;
177 
178   /** The arguments associated with this entry */
179   protected Vector   args = null;
180 
181   /**
182    * Null constructor; something for subclasses to call.
183    */
184   public CatalogEntry() {}
185 
186   /**
187    * Construct a catalog entry of the specified type.
188    *
189    * @param name The name of the entry type
190    * @param args A String Vector of arguments
191    * @throws InvalidCatalogEntryTypeException if no such entry type
192    * exists.
193    * @throws InvalidCatalogEntryException if the wrong number of arguments
194    * is passed.
195    */
196   public CatalogEntry(String   name, Vector   args)
197     throws CatalogException {
198     Integer   iType = (Integer  ) entryTypes.get(name);
199 
200     if (iType == null) {
201       throw new CatalogException(CatalogException.INVALID_ENTRY_TYPE);
202     }
203 
204     int type = iType.intValue();
205 
206     try {
207       Integer   iArgs = (Integer  ) entryArgs.get(type);
208       if (iArgs.intValue() != args.size()) {
209     throw new CatalogException(CatalogException.INVALID_ENTRY);
210       }
211     } catch (ArrayIndexOutOfBoundsException   e) {
212       throw new CatalogException(CatalogException.INVALID_ENTRY_TYPE);
213     }
214 
215     entryType = type;
216     this.args = args;
217   }
218 
219   /**
220    * Construct a catalog entry of the specified type.
221    *
222    * @param name The name of the entry type
223    * @param args A String Vector of arguments
224    * @throws InvalidCatalogEntryTypeException if no such entry type
225    * exists.
226    * @throws InvalidCatalogEntryException if the wrong number of arguments
227    * is passed.
228    */
229   public CatalogEntry(int type, Vector   args)
230     throws CatalogException {
231     try {
232       Integer   iArgs = (Integer  ) entryArgs.get(type);
233       if (iArgs.intValue() != args.size()) {
234     throw new CatalogException(CatalogException.INVALID_ENTRY);
235       }
236     } catch (ArrayIndexOutOfBoundsException   e) {
237       throw new CatalogException(CatalogException.INVALID_ENTRY_TYPE);
238     }
239 
240     entryType = type;
241     this.args = args;
242   }
243 
244   /**
245    * Get the entry type.
246    *
247    * @return The entry type of the CatalogEntry
248    */
249   public int getEntryType() {
250     return entryType;
251   }
252 
253   /**
254    * Get an entry argument.
255    *
256    * @param argNum The argument number (arguments are numbered from 0).
257    * @return The specified argument or null if an invalid argNum is
258    * provided.
259    */
260   public String   getEntryArg(int argNum) {
261     try {
262       String   arg = (String  ) args.get(argNum);
263       return arg;
264     } catch (ArrayIndexOutOfBoundsException   e) {
265       return null;
266     }
267   }
268 
269   /**
270    * Set an entry argument.
271    *
272    * <p>Catalogs sometimes need to adjust the catlog entry parameters,
273    * for example to make a relative URI absolute with respect to the
274    * current base URI. But in general, this function should only be
275    * called shortly after object creation to do some sort of cleanup.
276    * Catalog entries should not mutate over time.</p>
277    *
278    * @param argNum The argument number (arguments are numbered from 0).
279    * @throws ArrayIndexOutOfBoundsException if an invalid argument
280    * number is provided.
281    */
282   public void setEntryArg(int argNum, String   newspec)
283     throws ArrayIndexOutOfBoundsException   {
284     args.set(argNum, newspec);
285   }
286 }
287
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags