Transformer


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;
20  
21  import java.io.IOException  ;
22  import java.util.List  ;
23  
24  // Zeus imports
25  import org.enhydra.zeus.ZeusException;
26  import org.enhydra.zeus.transform.NoSuchValueEnumerationException;
27  import org.enhydra.zeus.transform.TransformerOptions;
28  import org.enhydra.zeus.transform.ValueEnumeration;
29  
30  /**
31   * <p>
32   *  <code>Transformer</code> is the interface for converting a set of Zeus
33   *    <code>{@link Binder}</code> objects from a set of XML-based names 
34   *    (created by a Zeus <code>{@link Binder}</code> instance) and
35   *    identities to another set of <code>Binding</code> objects. This second
36   *    set of objects is only an intermediate set, which is then used by a
37   *    <code>{@link Generator}</code> to create Java classes.
38   * </p><p>
39   *  This allows a user to specify a <i>mapping file</i> and thereby transform
40   *    a set of XML names into another set of names, either for ensuring legal
41   *    Java names, for using more business-centric names, or any other user
42   *    desired basis.
43   * </p>
44   *
45   * @author Brett McLaughlin
46   */
47  public interface Transformer {
48  
49      /**
50       * <p>
51       *  This allows setting of the <code>{@link TransformerOptions}</code> for
52       *    this transformer.
53       * </p>
54       *
55       * @param transformerOptions the options for this transformer
56       */
57      public void setTransformerOptions(TransformerOptions transformerOptions);
58      
59      /**
60       * <p>
61       *  This returns the current <code>{@link TransformerOptions}</code> for
62       *    this transformer.
63       * </p>
64       *
65       * @return <code>TransformerOptions</code> - the options in use for this
66       *         transformer.
67       */
68      public TransformerOptions getTransformerOptions();
69      
70      /**
71       * <p>
72       *  This will add a new <code>{@link ValueEnumeration}</code> to those
73       *    available to this <code>Transformer</code>.
74       * </p>
75       *
76       * @param valueEnumeration the enumeration to add for this transformer.
77       */
78      public void addValueEnumeration(ValueEnumeration valueEnumeration);
79      
80      /**
81       * <p>
82       *  This will retrieve the <code>{@link ValueEnumeration}</code> for the
83       *    supplied name.
84       * </p><p>
85       *  If the supplied name is not associated with a 
86       *    <code>ValueEnumeration<code>, this is considered an <i>exceptional</i>
87       *    condition; any <code>Transformer</code> construct looking for a
88       *    <code>ValueEnumeration</code> by name <i>expects</i> to find one,
89       *    or the supplied mapping information is in error. Therefore, 
90       *    in this case, a <code>{@link NoSuchValueEnumerationException}</code>
91       *    is thrown.
92       * </p>
93       *
94       * @return <code>ValueEnumeration</code> - the enumeration for the supplied
95       *         name.
96       * @throws <code>NoSuchValueEnumerationException</code> - when an
97       *         enumeration with the supplied name cannot be found.
98       */
99      public ValueEnumeration getValueEnumeration(String   name) 
100         throws NoSuchValueEnumerationException;
101 
102     /**
103      * <p>
104      *  This method performs the work of transforming a set of Zeus
105      *    <code>{@link Binding}</code> objects. It then returns a <i>new</i>
106      *    set of <code>Binding</code> objects (in <code>List</code> form)
107      *    with transformed names, types, and values.
108      * </p><p>
109      *  When this method is invoked, it attempts to see if parsing of the 
110      *    mapping file has already occurred. If it has not, parsing of that
111      *    file will occur within this method.
112      * </p><p>
113      *  It is important to note that the <i>number</i> of bindings returned
114      *    from this method may not be the same as the number supplied. This
115      *    is due to some XML elements/attributes being converted to value
116      *    objects, while other mapping instructions may actually create new
117      *    binding objects.
118      * </p>
119      *
120      * @param bindings <code>List</code> of bindings to process for
121      *        transformation.
122      * @return <code>List</code> - the transformed bindings.
123      * @throws <code>IOException</code> - when errors occur in parsing
124      *         a mapping configuration file.
125      * @throws <code>ZeusException</code> - when errors occuring in
126      *         transformation.
127      */
128     public List   transform(List   bindings) throws IOException  , ZeusException;
129 }
130
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags