CategoryService


1   package org.jahia.services.categories;
2   
3   import org.jahia.content.ObjectKey;
4   import org.jahia.exceptions.JahiaException;
5   import org.jahia.exceptions.JahiaInitializationException;
6   import org.jahia.services.JahiaInitializableService;
7   import org.jahia.settings.SettingsBean;
8   
9   import java.util.*;
10  
11  /**
12   * <p>Title: Category management service</p>
13   * <p>Description: Category management service, allows browsing of categories as
14   * well as navigation and manipulating categories and associated objects.
15   * This service should not be used directly but rather the Category class
16   * should be used to manipulate categories and associations.</p>
17   * <p>Copyright: Copyright (c) 2002</p>
18   * <p>Company: Jahia Ltd</p>
19   *
20   * @author Serge Huber
21   * @version 1.0
22   */
23  
24  public abstract class CategoryService extends JahiaInitializableService {
25  
26      /**
27       * Initializes the servlet dispatching service with parameters loaded
28       * from the Jahia configuration file.
29       *
30       * @param jSettings private settings object that contains Jahia
31       *                  configuration parameters
32       *
33       * @throws JahiaInitializationException thrown in the case of an error
34       *                                      during this initialization, that will be treated as a critical error
35       *                                      in Jahia and probably stop execution of Jahia once and for all.
36       */
37      public abstract void init (SettingsBean jSettings)
38          throws JahiaInitializationException;
39  
40      /**
41       * @return the root category object that corresponds to the start point
42       *         of the category tree.
43       *
44       * @throws JahiaException thrown if there was a problem communicating with
45       *                        the database
46       */
47      public abstract Category getRootCategory ()
48          throws JahiaException;
49  
50      /**
51       * @param key the key for the category to retrieve
52       *
53       * @return the category corresponding to the key if it exists in the
54       *         database
55       *
56       * @throws JahiaException thrown if there was a problem communicating with
57       *                        the database
58       */
59      public abstract Category getCategory (String   key)
60          throws JahiaException;
61  
62      /**
63       * @param categoryID the identifier of the category to retrieve from the
64       *                   database
65       *
66       * @return the category corresponding to the identifier if it exists in
67       *         the database, or null otherwise
68       *
69       * @throws JahiaException thrown if there was a problem communicating with
70       *                        the database
71       */
72      public abstract Category getCategory (int categoryID)
73          throws JahiaException;
74  
75      /**
76       * Retrieves the child object keys that are associated with the given
77       * parent category. The child objects might be refering to content objects
78       * or other objects such as sub-categories.
79       *
80       * @param parentCategory the category for which to retrieve the child
81       *                       object key list
82       *
83       * @return a list of ObjectKey objects that could be anything including
84       *         CategoryKey objects.
85       *
86       * @throws JahiaException thrown if there was a problem communicating with
87       *                        the database
88       */
89      public abstract ArrayList getCategoryChildKeys (Category parentCategory)
90          throws JahiaException;
91  
92      /**
93       * Add a new category under a specified category. This method performs
94       * both the operation of creating a new category and associating it with
95       * the parentCategory.
96       *
97       * @param newCategory    the new category to add
98       * @param parentCategory the parent category which will contain as a
99       *                       child the newCategory.
100      *
101      * @throws JahiaException thrown if there was a problem communicating with
102      *                        the database
103      */
104     public abstract void addCategory (Category newCategory,
105                                       Category parentCategory)
106         throws JahiaException;
107 
108     /**
109      * Removes a category and all the associations with it, including all the
110      * title translations.
111      *
112      * @param category the category to be removed
113      *
114      * @throws JahiaException thrown if there was a problem communicating with
115      *                        the database
116      */
117     public abstract void removeCategory (Category category)
118         throws JahiaException;
119 
120     /**
121      * Associate a category with an object key
122      *
123      * @param parentCategory the category that will be associated with the
124      *                       object key
125      * @param childKey       the object key that will become a "child" of the
126      *                       specified category.
127      *
128      * @throws JahiaException thrown if there was a problem communicating with
129      *                        the database
130      */
131     public abstract void addObjectKeyToCategory (Category parentCategory,
132                                                  ObjectKey childKey)
133         throws JahiaException;
134 
135     /**
136      * Remove an association between a category and an object key
137      *
138      * @param parentCategory the category currently involved in this association
139      * @param childKey       the category child object that we want to remove from
140      *                       this association
141      *
142      * @throws JahiaException thrown if there was a problem communicating with
143      *                        the database
144      */
145     public abstract void removeObjectKeyFromCategory (Category parentCategory,
146                                                       ObjectKey childKey)
147         throws JahiaException;
148 
149     /**
150      * Returns a set of categories with which this object is associated.
151      *
152      * @param objectKey the object key for the object for which to retrieve the
153      *                  categories
154      *
155      * @return a Set of Category objects.
156      *
157      * @throws JahiaException thrown if there was a problem communicating with
158      *                        the database.
159      */
160     public abstract Set getObjectCategories (ObjectKey objectKey)
161         throws JahiaException;
162 
163     /**
164      * Retrieves all titles in all locales for a category. Note that this
165      * is a raw retrieval.
166      *
167      * @param category the category for which to retrieve the title
168      *
169      * @return a String containing the titles for the category in the specified
170      *         locale if found, or null if not found. No resolving is done in the
171      *         "parent" locales by this method.
172      *
173      * @throws JahiaException thrown if there was a problem communicating with
174      *                        the database
175      */
176     public abstract Map getTitlesForCategory (Category category)
177             throws JahiaException;
178 
179     /**
180      * Retrieves a title in a certain locale for a category. Note that this
181      * is a raw retrieval, no locale resolution is done by this method.
182      *
183      * @param category the category for which to retrieve the title
184      * @param locale   the locale for which to retrieve the title
185      *
186      * @return a String containing the title for the category in the specified
187      *         locale if found, or null if not found. No resolving is done in the
188      *         "parent" locales by this method.
189      *
190      * @throws JahiaException thrown if there was a problem communicating with
191      *                        the database
192      */
193     public abstract String   getTitleForCategory (Category category,
194                                                 Locale locale)
195         throws JahiaException;
196 
197     /**
198      * Set a title for a category in a given locale. If the title existed
199      * previously it is overwritten, if it didn't exist it is created.
200      *
201      * @param category the category for which to set the title
202      * @param locale   the locale for which to set the title
203      * @param title    the title in the given locale
204      *
205      * @throws JahiaException thrown if there was a problem communicating with
206      *                        the database
207      */
208     public abstract void setTitleForCategory (Category category, Locale locale,
209                                               String   title)
210         throws JahiaException;
211 
212     /**
213      * Remove a title for a category in a given locale. This operation does
214      * nothing if the title didn't exist for the specified locale
215      *
216      * @param category the category for which to remove the title
217      * @param locale   the locale in which to remove the title
218      *
219      * @throws JahiaException thrown if there was a problem communicating with
220      *                        the database
221      */
222     public abstract void removeTitleForCategory (Category category,
223                                                  Locale locale)
224         throws JahiaException;
225 
226     /**
227      * Returns the date of the last modification on *any* category.
228      * @return Date the date of last modification on *any* category. Note that
229      * if this method returns null, it can mean either that no category was
230      * ever modified during this instance of Jahia, or that we received a
231      * flush from another node in the cluster !
232      */
233     public abstract Date getLastModificationDate ();
234 
235     /**
236      * Sets the date of last modification for *any* category to the date
237      * right now. Use this if you need to set this manually. Normally this
238      * should only be called from the Category facade, never elsewhere.
239      */
240     public abstract void setLastModificationDate();
241 
242 }
243
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags