KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > enhydra > zeus > 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 JavaDoc;
22 import java.util.List JavaDoc;
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 JavaDoc 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 JavaDoc transform(List JavaDoc bindings) throws IOException JavaDoc, ZeusException;
129 }
130
Popular Tags