BaseTransformer


1   /*
2    * Enhydra Java Application Server Project
3    * 
4    * The contents of this file are subject to the Enhydra Public License
5    * Version 1.1 (the "License"); you may not use this file except in
6    * compliance with the License. You may obtain a copy of the License on
7    * the Enhydra web site ( http://www.enhydra.org/ ).
8    * 
9    * Software distributed under the License is distributed on an "AS IS"
10   * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 
11   * the License for the specific terms governing rights and limitations
12   * under the License.
13   * 
14   * The Initial Developer of the Enhydra Application Server is Lutris
15   * Technologies, Inc. The Enhydra Application Server and portions created
16   * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
17   * All Rights Reserved.
18   */
19  package org.enhydra.zeus.transform;
20  
21  import java.util.HashMap  ;
22  import java.io.IOException  ;
23  import java.util.List  ;
24  import java.util.Map  ;
25  
26  // Zeus imports
27  import org.enhydra.zeus.Source;
28  import org.enhydra.zeus.Transformer;
29  import org.enhydra.zeus.ZeusException;
30  import org.enhydra.zeus.transform.ValueEnumeration;
31  
32  /**
33   * <p>
34   *  <code>{@link Transformer}</code> is the interface for converting a set of
35   *    Zeus <code>{@link org.enhydra.zeus.Binding}</code> objects from a set of 
36   *    XML-based names and identities (created by a Zeus 
37   *    <code>{@link org.enhydra.zeus.Binder}</code> instance) to another set of 
38   *    <code>Binding</code> objects. This second
39   *    set of objects is only an intermediate set, which is then used by a
40   *    <code>{@link org.enhydra.zeus.Generator}</code> to create Java classes.
41   * </p><p>
42   *  This allows a user to specify a <i>mapping file</i> and thereby transform
43   *    a set of XML names into another set of names, either for ensuring legal
44   *    Java names, for using more business-centric names, or any other user
45   *    desired basis.
46   * </p><p>
47   *  <code>BaseTransformer</code> is an abstract, base implementation of 
48   *    <code>Transformer</code>, and provides common functionality. All
49   *    <code>Transformer</code> implementations should extend this base class.
50   * </p>
51   *
52   * @author Brett McLaughlin
53   */
54  public abstract class BaseTransformer implements Transformer {
55      
56      /** The <code>{@link Source}</code> to read mapping information from */
57      protected Source source;
58      
59      /** The <code>{@link TransformerOptions}</code> for this transformer */
60      private TransformerOptions transformerOptions;
61      
62      /** The list of <code>ValueEnumeration</code>s for this transformer. */
63      private Map   valueEnumerations;
64      
65      /**
66       * <p>
67       *  This constructor takes in a <code>{@link Source}</code>
68       *    to read mapping information from and allow generation of the 
69       *    transformation mappings from it.
70       * </p>
71       *
72       * @param source <code>Source</code> to read mapping input from.
73       */
74      public BaseTransformer(Source source) {
75          // The only transformer allowed to have a null source is the default
76          if ((source == null) && !(this instanceof DefaultsTransformer)) {
77              throw new IllegalArgumentException  ("A Transformer cannot have " +
78                  "a null Source.");
79          }
80          this.source = source;
81          
82          // Initialize variables
83          transformerOptions = new TransformerOptions();
84          valueEnumerations = new HashMap  ();
85      }
86      
87      /**
88       * <p>
89       *  This allows setting of the <code>{@link TransformerOptions}</code> for
90       *    this transformer.
91       * </p>
92       *
93       * @param transformerOptions the options for this transformer
94       */
95      public void setTransformerOptions(TransformerOptions transformerOptions) {
96          if (transformerOptions == null) {
97              throw new IllegalArgumentException  ("A Transformer cannot " +
98                  "have a null set of TransformerOptions.");
99          }
100         this.transformerOptions = transformerOptions;
101     }
102     
103     /**
104      * <p>
105      *  This returns the current <code>{@link TransformerOptions}</code> for
106      *    this transformer.
107      * </p>
108      *
109      * @return <code>TransformerOptions</code> - the options in use for this
110      *         transformer.
111      */
112     public TransformerOptions getTransformerOptions() {
113         return transformerOptions;
114     }
115     
116     /**
117      * <p>
118      *  This will add a new <code>{@link ValueEnumeration}</code> to those
119      *    available to this <code>Transformer</code>.
120      * </p>
121      *
122      * @param valueEnumeration the enumeration to add for this transformer.
123      */
124     public void addValueEnumeration(ValueEnumeration valueEnumeration) {
125         if (valueEnumeration == null) {
126             throw new IllegalArgumentException  ("A Transformer cannot have " +
127                 "a null ValueEnumeration.");
128         }
129         valueEnumerations.put(valueEnumeration.getName(), valueEnumeration);
130     }
131     
132     /**
133      * <p>
134      *  This will retrieve the <code>{@link ValueEnumeration}</code> for the
135      *    supplied name.
136      * </p><p>
137      *  If the supplied name is not associated with a 
138      *    <code>ValueEnumeration<code>, this is considered an <i>exceptional</i>
139      *    condition; any <code>Transformer</code> construct looking for a
140      *    <code>ValueEnumeration</code> by name <i>expects</i> to find one,
141      *    or the supplied mapping information is in error. Therefore, 
142      *    in this case, a <code>{@link NoSuchValueEnumerationException}</code>
143      *    is thrown.
144      * </p>
145      *
146      * @return <code>ValueEnumeration</code> - the enumeration for the supplied
147      *         name.
148      * @throws <code>NoSuchValueEnumerationException</code> - when an
149      *         enumeration with the supplied name cannot be found.
150      */
151     public ValueEnumeration getValueEnumeration(String   name) 
152         throws NoSuchValueEnumerationException {
153             
154         ValueEnumeration valueEnumeration = 
155             (ValueEnumeration)valueEnumerations.get(name);
156             
157         // If no enumeration found, throw an exception
158         if (valueEnumeration == null) {
159             throw new NoSuchValueEnumerationException(name);
160         }
161         
162         // If we got here, return the located enumeration
163         return valueEnumeration;
164     }
165     
166     /**
167      * <p>
168      *  This method performs the work of transforming a set of Zeus
169      *    <code>{@link org.enhydra.zeus.Binding}</code> objects. It then 
170      *    returns a <i>new</i> set of <code>Binding</code> objects 
171      *    (in <code>List</code> form) with transformed names, types, and values.
172      * </p><p>
173      *  When this method is invoked, it attempts to see if parsing of the 
174      *    mapping file has already occurred. If it has not, parsing of that
175      *    file will occur within this method.
176      * </p><p>
177      *  It is important to note that the <i>number</i> of bindings returned
178      *    from this method may not be the same as the number supplied. This
179      *    is due to some XML elements/attributes being converted to value
180      *    objects, while other mapping instructions may actually create new
181      *    binding objects.
182      * </p>
183      *
184      * @param bindings <code>List</code> of bindings to process for
185      *        transformation.
186      * @return <code>List</code> - the transformed bindings.
187      * @throws <code>IOException</code> - when errors occur in parsing
188      *         a mapping configuration file.
189      * @throws <code>ZeusException</code> - when errors occuring in
190      *         transformation.
191      */
192     public List   transform(List   bindings) throws IOException  , ZeusException {
193         // Perform transformation, without recursion
194         return transform(bindings, false);
195     }
196     
197     /**
198      * <p>
199      *  This method performs the work of transforming a set of Zeus
200      *    <code>{@link org.enhydra.zeus.Binding}</code> objects. It then 
201      *    returns a <i>new</i> set of <code>Binding</code> objects 
202      *    (in <code>List</code> form) with transformed names, types, and values.
203      * </p><p>
204      *  When this method is invoked, it attempts to see if parsing of the 
205      *    mapping file has already occurred. If it has not, parsing of that
206      *    file will occur within this method.
207      * </p><p>
208      *  It is important to note that the <i>number</i> of bindings returned
209      *    from this method may not be the same as the number supplied. This
210      *    is due to some XML elements/attributes being converted to value
211      *    objects, while other mapping instructions may actually create new
212      *    binding objects.
213      * </p>
214      *
215      * @param bindings <code>List</code> of bindings to process for
216      *        transformation.
217      * @param recursing indication of if this is within a recursion loop.
218      * @return <code>List</code> - the transformed bindings.
219      * @throws <code>IOException</code> - when errors occur in parsing
220      *         a mapping configuration file.
221      * @throws <code>ZeusException</code> - when errors occuring in
222      *         transformation.
223      */
224     public abstract List   transform(List   bindings, boolean recursing) 
225         throws IOException  , ZeusException;
226 
227 }
228
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags