001 /**
002 *
003 * $Revision: 14450 $ $Date: 2008-11-21 11:54:03 +0100 (Fr, 21 Nov 2008) $
004 *
005 * This file is part of ** M y C o R e **
006 * Visit our homepage at http://www.mycore.de/ for details.
007 *
008 * This program is free software; you can use it, redistribute it
009 * and / or modify it under the terms of the GNU General Public License
010 * (GPL) as published by the Free Software Foundation; either version 2
011 * of the License or (at your option) any later version.
012 *
013 * This program is distributed in the hope that it will be useful, but
014 * WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program, normally in the file license.txt.
020 * If not, write to the Free Software Foundation Inc.,
021 * 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA
022 *
023 **/
024 package org.mycore.datamodel.classifications2;
025
026 import java.util.List;
027
028 /**
029 * Interface of the Data Access Object for Classifications.
030 *
031 * @author Thomas Scheffler (yagee)
032 * @version $Revision: 14450 $ $Date: 2008-11-21 11:54:03 +0100 (Fr, 21 Nov 2008) $
033 * @since 2.0
034 */
035 public interface MCRCategoryDAO {
036
037 /**
038 * Adds a category as child of another category.
039 *
040 * @param parentID
041 * ID of the parent category
042 * @param category
043 * Category (with children) to be added
044 */
045 public abstract void addCategory(MCRCategoryID parentID, MCRCategory category);
046
047 /**
048 * Deletes a category with all child categories.
049 *
050 * @param id
051 * ID of Category to be removed
052 */
053 public abstract void deleteCategory(MCRCategoryID id);
054
055 /**
056 * Tells if a given category exists.
057 *
058 * @param id
059 * ID of Category
060 * @return true if category is present
061 */
062 public abstract boolean exist(MCRCategoryID id);
063
064 /**
065 * Retrieve all Categories tagged by a specific label in a specific lang.
066 *
067 * @param baseID
068 * base Category which subtree is searched for the label.
069 * @param lang
070 * language attribute of the label
071 * @param text
072 * text of the label
073 * @return a collection of MCRCategories with matching labels
074 */
075 public abstract List<MCRCategory> getCategoriesByLabel(MCRCategoryID baseID, String lang, String text);
076
077 /**
078 * Returns MCRCategory with this id and childLevel levels of subcategories.
079 *
080 * @param id
081 * ID of category
082 * @param childLevel
083 * how many levels of subcategories should be retrieved (-1 for
084 * invinitive)
085 * @return MCRCategory with <code>id</code>
086 */
087 public abstract MCRCategory getCategory(MCRCategoryID id, int childLevel);
088
089 /**
090 * Returns the list of child categories for the specified category.
091 *
092 * @param id
093 * ID of category
094 * @return list of child category
095 */
096 public abstract List<MCRCategory> getChildren(MCRCategoryID id);
097
098 /**
099 * Returns the parent of the given category and its parent and so on. The
100 * last element in the list is the root category (the classification)
101 *
102 * @param id
103 * ID of Category
104 * @return list of parents
105 */
106 public abstract List<MCRCategory> getParents(MCRCategoryID id);
107
108 /**
109 * Returns all category IDs that do not have a parent category.
110 *
111 * @return list of category IDs
112 */
113 public abstract List<MCRCategoryID> getRootCategoryIDs();
114
115 /**
116 * Returns all categories that do not have a parent category.
117 *
118 * @return list of category IDs
119 */
120 public abstract List<MCRCategory> getRootCategories();
121
122 /**
123 * Returns the root Category with ancestor axis of the specified category
124 * and childLevel levels of subcategories.
125 *
126 * You can say it is the combination of getParents(MCRCategoryID) and
127 * getCategory(MCRCategoryID, int).
128 *
129 * @param baseID
130 * Category with relative level set to "0".
131 * @param childLevel
132 * amount of subcategory levels rooted at baseID category
133 * @return the root Category (Classification)
134 * @see #getParents(MCRCategoryID)
135 * @see #getCategory(MCRCategoryID, int)
136 */
137 public abstract MCRCategory getRootCategory(MCRCategoryID baseID, int childLevel);
138
139 /**
140 * Tells if a given category contains subcategories.
141 *
142 * @param id
143 * ID of Category
144 * @return true if subcategories are present
145 */
146 public abstract boolean hasChildren(MCRCategoryID id);
147
148 /**
149 * Moves a Category from one subtree in a classification to a new parent.
150 *
151 * All subcategories remain children of the moved category.
152 *
153 * @param id
154 * ID of the Category which should be moved
155 * @param newParentID
156 * ID of the new parent
157 */
158 public abstract void moveCategory(MCRCategoryID id, MCRCategoryID newParentID);
159
160 /**
161 * Moves a Category from one subtree in a classification to a new parent as
162 * the <code>index</code>th child.
163 *
164 * @param id
165 * ID of the Category which should be moved
166 * @param newParentID
167 * ID of the new parent
168 * @param index
169 * insert category at index in the list of children
170 */
171 public abstract void moveCategory(MCRCategoryID id, MCRCategoryID newParentID, int index);
172
173 /**
174 * Removes a label from a Category.
175 *
176 * @param id
177 * ID of the category
178 * @param lang
179 * which language should be removed?
180 */
181 public abstract void removeLabel(MCRCategoryID id, String lang);
182
183 /**
184 * Replaces a <code>MCRCategory</code> by a new version of the same
185 * category.
186 *
187 * This replacment includes all subcategories and labels. So former
188 * subcategories and labels not present in <code>newCategory</code> will
189 * be removed while new ones will be inserted.
190 *
191 * If you can use the other methods defined by this interface as they ought
192 * to be more optimized.
193 *
194 * @param newCategory
195 * new version of MCRCategory
196 * @throws IllegalArgumentException
197 * if old version of MCRCategory does not exist
198 */
199 public abstract void replaceCategory(MCRCategory newCategory) throws IllegalArgumentException;
200
201 /**
202 * Sets or updates a label from a Category.
203 *
204 * @param id
205 * ID of the category
206 * @param label
207 * to be set or updated
208 */
209 public abstract void setLabel(MCRCategoryID id, MCRLabel label);
210
211 /**
212 * allows to determine when the last change was made to the categories.
213 * @return either the last change time or the init time of the DAO class
214 */
215 public abstract long getLastModified();
216
217 }