1 package de.fhdw.wtf.persistence.facade;
2
3 import java.util.Collection;
4 import java.util.List;
5
6 import de.fhdw.wtf.persistence.exception.ClassFacadeUninitializedException;
7 import de.fhdw.wtf.persistence.exception.DuplicateUserTypeException;
8 import de.fhdw.wtf.persistence.exception.PersistenceException;
9 import de.fhdw.wtf.persistence.meta.Association;
10 import de.fhdw.wtf.persistence.meta.MapAssociation;
11 import de.fhdw.wtf.persistence.meta.Type;
12 import de.fhdw.wtf.persistence.meta.UnidirectionalAssociation;
13 import de.fhdw.wtf.persistence.meta.UserType;
14
15 /**
16 * A facade to access objects in the database which represent types and associations.
17 *
18 */
19 public interface ClassFacade {
20
21 /**
22 * Constructor for a new User Type.
23 *
24 * @param name
25 * The name of the {@link de.fhdw.wtf.persistence.meta.UserType User Type}.
26 * @param abs
27 * A boolean flag indicating whether this {@link de.fhdw.wtf.persistence.meta.UserType User Type} is
28 * abstract or not
29 * @param transaction
30 * A boolean flag indicating whether this {@link de.fhdw.wtf.persistence.meta.UserType User Type} is also
31 * an Transaction or not.
32 * @return Provides a new {@link de.fhdw.wtf.persistence.meta.UserType} with the given attributes and the next
33 * possible id.
34 * @throws PersistenceException
35 * A persistence Exception is thrown if any Error contacting the database occurs.
36 * @throws DuplicateUserTypeException
37 * can be thrown if the attempt is made to create an {@link de.fhdw.wtf.persistence.meta.UserType} with
38 * an already existing name.
39 */
40 UserType createUserType(String name, boolean abs, boolean transaction) throws PersistenceException,
41 DuplicateUserTypeException;
42
43 /**
44 * Constructor for a new {@link de.fhdw.wtf.persistence.meta.UnidirectionalAssociation}.
45 *
46 * @param name
47 * The name of the new {@link de.fhdw.wtf.persistence.meta.UnidirectionalAssociation}.
48 * @param essential
49 * A boolean flag indicating whether there is an existing object necessary.
50 * @param unique
51 * A boolean flag indicating whether the association is set-valued.
52 * @param owner
53 * The owning side of the {@link de.fhdw.wtf.persistence.meta.UnidirectionalAssociation}
54 * @param target
55 * The targeting side of the {@link de.fhdw.wtf.persistence.meta.UnidirectionalAssociation}.
56 * @return Provides a new {@link de.fhdw.wtf.persistence.meta.UnidirectionalAssociation} with the given attributes
57 * and the next possible ID.
58 * @throws PersistenceException
59 * A {@link de.fhdw.wtf.persistence.exception.PersistenceException persistence exception} is thrown if
60 * any error contacting the database occurs.
61 */
62 UnidirectionalAssociation createUnidirectionalAssociation(String name,
63 boolean essential,
64 boolean unique,
65 UserType owner,
66 Type target) throws PersistenceException;
67
68 /**
69 * Constructor for a new MapAssociation.
70 *
71 * @param name
72 * The name of the new MapAssociation.
73 * @param essential
74 * A boolean flag indicating whether there is an existing object necessary.
75 * @param owner
76 * The owner side of the MapAssociation.
77 * @param target
78 * The targeting side of the MapAssociation.
79 * @param keyType
80 * The map-key type of the MapAssociation, when the MapAssociation is a map.
81 * @return Provides a new MapAssociation with the given attributes and the next possible ID.
82 * @throws PersistenceException
83 * A persistence Exception is thrown if any Error contacting the database occurs.
84 */
85 MapAssociation createMapAssociation(String name, boolean essential, UserType owner, Type target, Type keyType)
86 throws PersistenceException;
87
88 /**
89 * Creates a specialization-relationship between two user types.
90 *
91 * @param ancestor
92 * The Ancestor which means the super type in the specialization
93 * @param descendant
94 * The descendant which means the sub type in the specialization
95 * @throws PersistenceException
96 * A persistence Exception is thrown if any Error contacting the database occurs.
97 */
98 void createSpecializationBetween(UserType ancestor, Type descendant) throws PersistenceException;
99
100 /**
101 * Checks if one Type is Superior to another.
102 *
103 * @param ancestor
104 * The given super type.
105 * @param descendant
106 * The given sub type.
107 * @return Provides true if the ancestor is a supertype to descendant.
108 * @throws PersistenceException
109 * A persistence Exception is thrown if any Error contacting the database occurs.
110 */
111 boolean isSuperClassTo(Type ancestor, Type descendant) throws PersistenceException;
112
113 /**
114 * When creating specializations, they will be stored in a normalized manner inside the database, which means that
115 * the Facade can only determine if direct specializations exist. Reflexive and transitive Specializations could not
116 * be detected. This Method creates the reflexive, transitive closure.
117 *
118 * @throws PersistenceException
119 * A persistence Exception is thrown if any Error contacting the database occurs.
120 */
121 void finalizeSpecialization() throws PersistenceException;
122
123 /**
124 * Attention !!! This Method deletes every Type, UnidirectionalAssociation an specialization in the database. This
125 * means it should be used very carefully.
126 *
127 * @throws PersistenceException
128 * A persistence Exception is thrown if any Error contacting the database occurs.
129 */
130 void clear() throws PersistenceException;
131
132 /**
133 * Renaming the given Type discarding the old name.
134 *
135 * @param typeId
136 * the id of the Type which should renamed
137 * @param newName
138 * the new name of the type
139 * @throws PersistenceException
140 * A persistence Exception is thrown if any Error contacting the database occurs.
141 */
142 void renameType(Long typeId, String newName) throws PersistenceException;
143
144 /**
145 * Renaming the given Association discarding the old name.
146 *
147 * @param assoId
148 * the id of the Association which should renamed
149 * @param newName
150 * the new name of the association
151 * @throws PersistenceException
152 * A persistence Exception is thrown if any Error contacting the database occurs.
153 */
154 void renameAssociation(Long assoId, String newName) throws PersistenceException;
155
156 /**
157 * Removes this association permanently. Attention: This function must only be called on associations that have no
158 * links!
159 *
160 * @param associationId
161 * to be removed
162 * @throws PersistenceException
163 * A persistence Exception is thrown if any Error contacting the database occurs.
164 */
165 void deleteAssociation(Long associationId) throws PersistenceException;
166
167 /**
168 * Removes this user type and corresponding specializations permanently. Attention: This function must only be
169 * called on types that have no direct objects!
170 *
171 * @param typeId
172 * to be removed
173 * @throws PersistenceException
174 * A persistence Exception is thrown if any Error contacting the database occurs.
175 */
176 void deleteUserType(Long typeId) throws PersistenceException;
177
178 /**
179 * Updates the instance-of relation of all links of 'association' to a matching new association in
180 * 'newAssociations'.
181 *
182 * @param associationId
183 * to be removed
184 * @param newAssociationIds
185 * new associations that links might have as new 'instance-of'
186 * @throws PersistenceException
187 * A persistence Exception is thrown if any Error contacting the database occurs.
188 */
189 void updateLinksToNewAssociation(Long associationId, Collection<Long> newAssociationIds)
190 throws PersistenceException;
191
192 /**
193 * Updates all existing links and adds objects and links to perform the move from the old associations to the new
194 * associations, that have moved to the new type.
195 *
196 * @param oldAssoIds
197 * @param newAsso
198 * @param newType
199 * @param newAssoIds
200 * @throws PersistenceException
201 */
202 void moveLinksAndCreateObjects(List<Long> oldAssoIds, Association newAsso, UserType newType, List<Long> newAssoIds)
203 throws PersistenceException;
204
205 /**
206 *
207 * This Method creates the Base Types in the Database and makes it possible to fill the model layer with content.
208 * This Method has to be called if there are no Model Items present in the Database and you want to create a new
209 * pool of data.
210 *
211 * @throws PersistenceException
212 * A persistence Exception is thrown if any Error contacting the database occurs.
213 */
214 void initialize() throws PersistenceException;
215
216 /**
217 * This method initializes the classfacade when there is already a model present in the database and the persistence
218 * facade has to be set up for Runtime. It reads the Type Information from the Database and store it into the
219 * TypeManager.
220 *
221 * @throws PersistenceException
222 * A persistence exception is thrown if there are any errors contacting the database.
223 */
224 void initializeForRuntime() throws PersistenceException;
225
226 /**
227 * A Method to determine if the classfacade has been initialized with at least Base type Informations. It is
228 * necessary that this methods provides true before executing other Database operations.
229 *
230 * @return Provides true if initialize or initializeWithExistingData had been invoked.
231 */
232 boolean hasBeenInitialized();
233
234 /**
235 * Provides the Type Manager, which represents a Dictionary for all created Classes and Associations, so it can be
236 * used to lookup Classes. This Method could only be used if initialize or initializeWithExistingData are invoked.
237 *
238 * @return The Type Manager, which stores Information about all Types and Associatons
239 * @throws ClassFacadeUninitializedException
240 * this exception were thrown when the classfacase isn't initialized
241 */
242 TypeManager getTypeManager() throws ClassFacadeUninitializedException;
243
244 }