01: /*
02: * (c) Copyright 2006 by Volker Bergmann. All rights reserved.
03: *
04: * Redistribution and use in source and binary forms, with or without
05: * modification, is permitted under the terms of the
06: * GNU General Public License.
07: *
08: * For redistributing this software or a derivative work under a license other
09: * than the GPL-compatible Free Software License as defined by the Free
10: * Software Foundation or approved by OSI, you must first obtain a commercial
11: * license to this software product from Volker Bergmann.
12: *
13: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
14: * WITHOUT A WARRANTY OF ANY KIND. ALL EXPRESS OR IMPLIED CONDITIONS,
15: * REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF
16: * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
17: * HEREBY EXCLUDED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
18: * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
19: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
20: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
21: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
22: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
23: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
24: * POSSIBILITY OF SUCH DAMAGE.
25: */
26:
27: package org.databene.benerator;
28:
29: /**
30: * This is the basic Generator interface, the mother of all generators.<br/>
31: * <br/>
32: * <b>Generator States</b><br/>
33: * A Generator may be in one of three states:
34: * <ul>
35: * <li><i>constructing</i>: The generator is under construction.
36: * This may take several steps, since generators need to be JavaBeans.
37: * The generator may transit into the available state automatically
38: * or manually when the validate() method is called.</li>
39: * <li><i>available</i>: Generator construction is done and the generator is available.
40: * The user may loop the Generator via available() and generate().</li>
41: * <li><i>unavailable</i>: The Generator may become unavailable automatically if its value space is depleted or
42: * manually when close() has been invoked. The Generator may be made <i>available</i> again by calling reset().
43: * When <i>unavailable</i>, the generator must be in a state in which it can be safely garbage collected.</li>
44: * </ul>
45: *
46: * <b>Developer Notes:</b><br/>
47: * When implementing a custom generator, make it a JavaBean:
48: * <ul>
49: * <li>Implement a public default (no-arg) constructor</li>
50: * <li>make each relevant property configurable by a set-method</li>
51: * </ul>
52: *
53: * Created: 07.06.2006 18:51:28
54: */
55: public interface Generator<E> {
56:
57: /**
58: * This is a convenience method for checking the validity of a Generator's setup.
59: * If setup is not alright, the validate() method is expected to throw an InvalidGeneratorSetupException.
60: * <br/>
61: * <b>Developer Notes:</b><br/>
62: * If the method finishes without exception, the generator has to be <i>available</i>. The next invocation of generate()
63: * is expected to return a valid product and available() is expected to return true.
64: * Be aware that this method does not need to be called by the user.
65: */
66: void validate();
67:
68: /**
69: * Returns an instance of the generic tpe P. If the method is called in an inappropriate state
70: * (<i>constructing</i> or <i>unavailable</i>), it will throw an IllegalGeneratorStateException.
71: */
72: E generate();
73:
74: /**
75: * Resets the generator to the initial state.
76: * When called, the Generator is expected to act as if 'restarted'.
77: * After invocation the state has to be <i>available</i>.
78: */
79: void reset();
80:
81: /**
82: * Closes the generator. After invocation the state is <i>unavailable</i>.
83: */
84: void close();
85:
86: /**
87: * Tells if the Generator is in <i>available</i> state. If this returns <i>true</i>,
88: * the next invocation of generate() must return a valid product.
89: */
90: boolean available();
91:
92: /**
93: * Declares the type of the objects returned by the generate() method.
94: */
95: Class<E> getGeneratedType();
96: }
|