1 /**
2 * AUTOHIT 2003
3 * Copyright Erich P Gatejen (c) 1989,1997,2003,2004
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or (at
8 * your option) any later version.
9 * This program is distributed in the hope that it will be useful, but
10 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
11 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
12 * more details.
13 *
14 * You should have received a copy of the GNU General Public License along
15 * with this program; if not, write to the Free Software Foundation, Inc.,
16 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 *
18 * Additional license information can be found in the documentation.
19 * @author Erich P Gatejen
20 */
21 package autohit.universe;
22
23 import java.io.InputStream;
24 import java.io.OutputStream;
25
26 import javax.activation.DataSource;
27 import javax.activation.FileDataSource;
28
29 /**
30 * Universe server interface. The locking mechinism is
31 * optional.
32 *
33 * @author Erich P. Gatejen
34 * @version 1.0
35 * <i>Version History</i>
36 * <code>EPG - New - 18Apr03</code>
37 *
38 */
39 public interface Universe {
40
41 /**
42 * This will always be called when the universe server is created.
43 * It is the one and only chance to get a reference to the properties
44 * file and do any post-construction setup.
45 * @param props a universe property set
46 * @return the loaded object
47 * @see autohit.universe.UniverseProperties
48 * @throws autohit.universe.UniverseException
49 */
50 public void genesis(UniverseProperties props) throws UniverseException;
51
52 /**
53 * This will always be called when the universe is destroyed
54 * @throws autohit.universe.UniverseException
55 */
56 public void close() throws UniverseException;
57
58 /**
59 * Load an object from the universe. (Not a class! It is possible
60 * that this is a shared, loaded object. That is up to the implimentor.)
61 * @param name universe name
62 * @return the loaded object
63 * @throws autohit.universe.UniverseException
64 */
65 public Object get(String name) throws UniverseException;
66
67 /**
68 * Load an object from the universe. Guarantee it is a unique
69 * instance of it.
70 * @param name universe name
71 * @return the loaded object
72 * @throws autohit.universe.UniverseException
73 */
74 public Object getUnique(String name) throws UniverseException;
75
76 /**
77 * Reserve unique object universe. Guarantee it is a unique
78 * instance of it. Great for temp objects.
79 * @param base base path for the object (including root object name)
80 * @return name of the reserved unique object.
81 * @throws autohit.universe.UniverseException
82 */
83 public String reserveUnique(String base) throws UniverseException;
84
85 /**
86 * Get an InputStream that can read from a universe object
87 * @param name universe name
88 * @return a stream to the object
89 * @throws autohit.universe.UniverseException
90 */
91 public InputStream getStream(String name) throws UniverseException;
92
93 /**
94 * Get a DataSource that can interact with this universe object
95 * @param name universe name
96 * @return a data source
97 * @throws autohit.universe.UniverseException
98 */
99 public DataSource getDataSource(String name) throws UniverseException;
100
101 /**
102 * Get a FileDataSource that can interact with this universe object.
103 * The universe must handle making sure the object at least appears local to the
104 * FileDataSource
105 * @param name universe name
106 * @return a data source
107 * @throws autohit.universe.UniverseException
108 */
109 public FileDataSource getFileDataSource(String name) throws UniverseException;
110
111
112 /**
113 * Save an object into the universe. It should use standard serialization.
114 * If this won't work correctly, then serialize it yourself to saveStream(String name, OutputStream s).
115 * @param name universe name
116 * @param o the object
117 * @throws autohit.universe.UniverseException
118 */
119 public void put(String name, Object o) throws UniverseException;
120
121 /**
122 * Get an output stream to a universe object. Caller responsible
123 * for streaming and closing.
124 * @param name universe name
125 * @return a stream to the object
126 * @throws autohit.universe.UniverseException
127 */
128 public OutputStream putStream(String name) throws UniverseException;
129
130 /**
131 * Lock an object. This is blocking.
132 * @param name universe name
133 * @throws autohit.universe.UniverseException
134 */
135 public void lock(String name) throws UniverseException;
136
137 /**
138 * Lock an object. This is NON blocking.
139 * @param name universe name
140 * @return true if lock completed, false is already locked
141 * @throws autohit.universe.UniverseException
142 */
143 public boolean lockIfNotLocked(String name) throws UniverseException;
144
145 /**
146 * Check to see if the object is locked
147 * @param name universe name
148 * @return true if the object is locked, otherwise false
149 * @throws autohit.universe.UniverseException
150 */
151 public boolean isLocked(String name) throws UniverseException;
152
153 /**
154 * Release a lock on an object.
155 * @param name universe name
156 * @throws autohit.universe.UniverseException
157 */
158 public void release(String name) throws UniverseException;
159
160 /**
161 * Check to see if an object exists
162 * @param name universe name
163 * @return true if the object exists, otherwise false
164 * @throws autohit.universe.UniverseException
165 */
166 public boolean exists(String name) throws UniverseException;
167
168 /**
169 * Flush an object. Typically not useful unless caching is implemented
170 * @param name universe name
171 * @return true if the object exists, otherwise false
172 * @throws autohit.universe.UniverseException
173 */
174 public void flush(String name) throws UniverseException;
175
176 /**
177 * Discard an object. Typically not useful unless caching is implemented
178 * @param name universe name
179 * @return true if the object exists, otherwise false
180 * @throws autohit.universe.UniverseException
181 */
182 public void discard(String name) throws UniverseException;
183
184 /**
185 * Remove an object from the universe
186 * @param name universe name
187 * @return true if the object exists, otherwise false
188 * @throws autohit.universe.UniverseException
189 */
190 public void remove(String name) throws UniverseException;
191
192 /**
193 * Report the size object from the universe
194 * @param name universe name
195 * @return the size or 0 if empty
196 * @throws autohit.universe.UniverseException
197 */
198 public long size(String name) throws UniverseException;
199
200 }
|