1 /*
2 * This file is part of *** M y C o R e ***
3 * See http://www.mycore.de/ for details.
4 *
5 * MyCoRe 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 3 of the License, or
8 * (at your option) any later version.
9 *
10 * MyCoRe is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with MyCoRe. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19 package org.mycore.datamodel.classifications2;
20
21 import java.net.URI;
22 import java.util.Collection;
23 import java.util.List;
24 import java.util.SortedSet;
25
26 /**
27 * Interface of the Data Access Object for Classifications.
28 *
29 * @author Thomas Scheffler (yagee)
30 * @version $Revision$ $Date$
31 * @since 2.0
32 */
33 public interface MCRCategoryDAO {
34
35 /**
36 * Adds a category as child of another category.
37 * When parentID is null a root category will be created.
38 *
39 * @param parentID
40 * ID of the parent category
41 * @param category
42 * Category (with children) to be added
43 * @return the parent category
44 */
45 MCRCategory addCategory(MCRCategoryID parentID, MCRCategory category);
46
47 /**
48 * Adds a category as child of another category.
49 * When parentID is null a root category will be created.
50 *
51 * @param parentID
52 * ID of the parent category
53 * @param category
54 * Category (with children) to be added
55 * @param position
56 * insert position
57 * @return the parent category
58 */
59 MCRCategory addCategory(MCRCategoryID parentID, MCRCategory category, int position);
60
61 /**
62 * Deletes a category with all child categories.
63 *
64 * @param id
65 * ID of Category to be removed
66 */
67 void deleteCategory(MCRCategoryID id);
68
69 /**
70 * Tells if a given category exists.
71 *
72 * @param id
73 * ID of Category
74 * @return true if category is present
75 */
76 boolean exist(MCRCategoryID id);
77
78 /**
79 * Retrieve all Categories tagged by a specific label in a specific lang.
80 *
81 * @param baseID
82 * base Category which subtree is searched for the label.
83 * @param lang
84 * language attribute of the label
85 * @param text
86 * text of the label
87 * @return a collection of MCRCategories with matching labels
88 */
89 List<MCRCategory> getCategoriesByLabel(MCRCategoryID baseID, String lang, String text);
90
91 /**
92 * Retrieve all Categories tagged by a specific label in a specific lang.
93 *
94 * @param lang
95 * language attribute of the label
96 * @param text
97 * text of the label
98 * @return a collection of MCRCategories with matching labels
99 */
100 List<MCRCategory> getCategoriesByLabel(String lang, String text);
101
102 /**
103 * Returns MCRCategory with this id and childLevel levels of subcategories.
104 *
105 * @param id
106 * ID of category
107 * @param childLevel
108 * how many levels of subcategories should be retrieved (-1 for
109 * infinitive)
110 * @return MCRCategory with <code>id</code> or null if the category cannot be found
111 */
112 MCRCategory getCategory(MCRCategoryID id, int childLevel);
113
114 /**
115 * Returns the list of child categories for the specified category.
116 *
117 * @param id
118 * ID of category
119 * @return list of child category
120 */
121 List<MCRCategory> getChildren(MCRCategoryID id);
122
123 /**
124 * Returns the parent of the given category and its parent and so on. The
125 * last element in the list is the root category (the classification)
126 *
127 * @param id
128 * ID of Category
129 * @return list of parents
130 */
131 List<MCRCategory> getParents(MCRCategoryID id);
132
133 /**
134 * Returns all category IDs that do not have a parent category.
135 *
136 * @return list of category IDs
137 */
138 List<MCRCategoryID> getRootCategoryIDs();
139
140 /**
141 * Returns all categories that do not have a parent category.
142 *
143 * @return list of category IDs
144 */
145 List<MCRCategory> getRootCategories();
146
147 /**
148 * Returns the root Category with ancestor axis of the specified category
149 * and childLevel levels of subcategories.
150 *
151 * You can say it is the combination of getParents(MCRCategoryID) and
152 * getCategory(MCRCategoryID, int).
153 *
154 * @param baseID
155 * Category with relative level set to "0".
156 * @param childLevel
157 * amount of subcategory levels rooted at baseID category
158 * @return the root Category (Classification)
159 * @see #getParents(MCRCategoryID)
160 * @see #getCategory(MCRCategoryID, int)
161 */
162 MCRCategory getRootCategory(MCRCategoryID baseID, int childLevel);
163
164 /**
165 * Tells if a given category contains subcategories.
166 *
167 * @param id
168 * ID of Category
169 * @return true if subcategories are present
170 */
171 boolean hasChildren(MCRCategoryID id);
172
173 /**
174 * Moves a Category from one subtree in a classification to a new parent.
175 *
176 * All subcategories remain children of the moved category.
177 *
178 * @param id
179 * ID of the Category which should be moved
180 * @param newParentID
181 * ID of the new parent
182 */
183 void moveCategory(MCRCategoryID id, MCRCategoryID newParentID);
184
185 /**
186 * Moves a Category from one subtree in a classification to a new parent as
187 * the <code>index</code>th child.
188 *
189 * @param id
190 * ID of the Category which should be moved
191 * @param newParentID
192 * ID of the new parent
193 * @param index
194 * insert category at index in the list of children
195 */
196 void moveCategory(MCRCategoryID id, MCRCategoryID newParentID, int index);
197
198 /**
199 * Removes a label from a Category.
200 *
201 * @param id
202 * ID of the category
203 * @param lang
204 * which language should be removed?
205 * @return category where the label was removed
206 */
207 MCRCategory removeLabel(MCRCategoryID id, String lang);
208
209 /**
210 * Replaces a <code>MCRCategory</code> by a new version of the same
211 * category.
212 *
213 * This replacment includes all subcategories and labels. So former
214 * subcategories and labels not present in <code>newCategory</code> will
215 * be removed while new ones will be inserted.
216 *
217 * If you can use the other methods defined by this interface as they ought
218 * to be more optimized.
219 *
220 * @param newCategory
221 * new version of MCRCategory
222 * @throws IllegalArgumentException
223 * if old version of MCRCategory does not exist
224 * @return collection of replaced categories
225 */
226 Collection<? extends MCRCategory> replaceCategory(MCRCategory newCategory)
227 throws IllegalArgumentException;
228
229 /**
230 * Sets or updates a label from a Category.
231 *
232 * @param id
233 * ID of the category
234 * @param label
235 * to be set or updated
236 * @return category where the label was set
237 */
238 MCRCategory setLabel(MCRCategoryID id, MCRLabel label);
239
240 /**
241 * Sets a new set of labels from a Category.
242 *
243 * @param id
244 * ID of the category
245 * @param labels
246 * to be set
247 * @return category where the labels was set
248 */
249 MCRCategory setLabels(MCRCategoryID id, SortedSet<MCRLabel> labels);
250
251 /**
252 * Sets or updates the URI from a Category.
253 *
254 * @param id
255 * ID of the category
256 * @param uri
257 * to be set or updated
258 * @return category where the uri was set
259 */
260 MCRCategory setURI(MCRCategoryID id, URI uri);
261
262 /**
263 * allows to determine when the last change was made to the categories.
264 * @return either the last change time or the init time of the DAO class
265 */
266 long getLastModified();
267
268 /**
269 * Gets the last modified timestamp for the given root id. If there is no timestamp at the moment -1 is returned.
270 *
271 * @param root ID of root category
272 *
273 * @return the last modified timestamp (if any) or -1
274 */
275 long getLastModified(String root);
276 }