001: /*
002: * Copyright (c) 2001 - 2005 ivata limited.
003: * All rights reserved.
004: * -----------------------------------------------------------------------------
005: * ivata groupware may be redistributed under the GNU General Public
006: * License as published by the Free Software Foundation;
007: * version 2 of the License.
008: *
009: * These programs are free software; you can redistribute them and/or
010: * modify them under the terms of the GNU General License
011: * as published by the Free Software Foundation; version 2 of the License.
012: *
013: * These programs are distributed in the hope that they will be useful,
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
016: *
017: * See the GNU General License in the file LICENSE.txt for more
018: * details.
019: *
020: * If you would like a copy of the GNU General License write to
021: *
022: * Free Software Foundation, Inc.
023: * 59 Temple Place - Suite 330
024: * Boston, MA 02111-1307, USA.
025: *
026: *
027: * To arrange commercial support and licensing, contact ivata at
028: * http://www.ivata.com/contact.jsp
029: * -----------------------------------------------------------------------------
030: * $Log: AddressBook.java,v $
031: * Revision 1.6 2005/10/11 18:53:07 colinmacleod
032: * Fixed some checkstyle and javadoc issues.
033: *
034: * Revision 1.5 2005/10/03 10:21:13 colinmacleod
035: * Fixed some style and javadoc issues.
036: *
037: * Revision 1.4 2005/04/29 02:48:14 colinmacleod
038: * Data bugfixes.
039: * Changed primary key back to Integer.
040: *
041: * Revision 1.3 2005/04/10 20:09:33 colinmacleod
042: * Added new themes.
043: * Changed id type to String.
044: * Changed i tag to em and b tag to strong.
045: * Improved PicoContainerFactory with NanoContainer scripts.
046: *
047: * Revision 1.2 2005/04/09 17:19:06 colinmacleod
048: * Changed copyright text to GPL v2 explicitly.
049: *
050: * Revision 1.1.1.1 2005/03/10 17:50:18 colinmacleod
051: * Restructured ivata op around Hibernate/PicoContainer.
052: * Renamed ivata groupware.
053: *
054: * Revision 1.5 2004/11/12 18:17:10 colinmacleod
055: * Ordered imports.
056: *
057: * Revision 1.4 2004/11/12 15:56:47 colinmacleod
058: * Removed dependencies on SSLEXT.
059: * Moved Persistence classes to ivata masks.
060: *
061: * Revision 1.3 2004/07/18 21:59:12 colinmacleod
062: * Removed Person from User - now you need to use addressbook/persistence
063: * manager to find the person (makes the app run faster.)
064: *
065: * Revision 1.2 2004/07/13 19:41:13 colinmacleod
066: * Moved project to POJOs from EJBs.
067: * Applied PicoContainer to services layer (replacing session EJBs).
068: * Applied Hibernate to persistence layer (replacing entity EJBs).
069: *
070: * Revision 1.1 2004/03/26 21:34:35 colinmacleod
071: * Split off functionality into POJO.
072: * -----------------------------------------------------------------------------
073: */
074: package com.ivata.groupware.business.addressbook;
075:
076: import java.util.List;
077:
078: import com.ivata.groupware.admin.security.server.SecuritySession;
079: import com.ivata.groupware.business.addressbook.address.AddressDO;
080: import com.ivata.groupware.business.addressbook.address.country.CountryDO;
081: import com.ivata.groupware.business.addressbook.person.PersonDO;
082: import com.ivata.groupware.business.addressbook.person.group.GroupDO;
083: import com.ivata.mask.util.SystemException;
084: import com.ivata.mask.validation.ValidationErrors;
085:
086: /**
087: * <p>
088: * In the beginning there was <strong>ivata groupware</strong> (well actually,
089: * it was called ivata op), but whatever it was made up of these parts:
090: * </p>
091: *
092: * <ul>
093: * <li>Address Book (<em>"Contacts"</em>)</li>
094: * <li>Calendar</li>
095: * <li>Library (<em>now called "ivata cms"</em>)</li>
096: * <li>WebMail</li>
097: * </ul>
098: *
099: * <p>
100: * This interface defines the address book <em>facade</em> - between the
101: * server-side data model, and the client-side user interface. It defines
102: * methods to add people and groups, change their values and obtain country
103: * information.
104: * </p>
105: *
106: * <p>
107: * The actual implementation is defined by {@link
108: * org.picocontainer.PicoContainer PicoContainer} - it might by a Plain Old Java
109: * Object, or it might be an EJB. Whatever, throughout the system, whenever a
110: * class needs the functions of the address book it includes the interface
111: * in its constructor (not an concrete class), and it gets the 'right'
112: * implementataion for the current system - automagically.
113: * </p>
114: *
115: *
116: * @author Colin MacLeod
117: * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
118: * @since ivata groupware 0.9 (Mar 22, 2004)
119: * @version $Revision: 1.6 $
120: */
121: public interface AddressBook {
122: /**
123: * Unique name used to refer to the message resources for this part of the
124: * system.
125: */
126: String BUNDLE_PATH = "addressBook";
127:
128: /**
129: * Add a new address book to the system.
130: *
131: * @param securitySession Used to validate the current user can add the
132: * address book.
133: * @param groupDO Address book group to be added.
134: * @return The new address book group, as stored in the system.
135: * @throws SystemException If the address book cannot be added for any
136: * reason.
137: */
138: GroupDO addAddressBook(final SecuritySession securitySession,
139: final GroupDO groupDO) throws SystemException;
140:
141: /**
142: * <p>Add a new group to the address book.</p>
143: *
144: * @param securitySession Used to validate the current user can add the
145: * group.
146: * @param groupDO a data object containing all the details
147: * of the group to add.
148: * @return the new group data object, with the details as they
149: * now are in the address book.
150: * @throws SystemException If the group cannot be added for any
151: * reason.
152: */
153: GroupDO addGroup(final SecuritySession securitySession,
154: final GroupDO groupDO) throws SystemException;
155:
156: /**
157: * <p>Add a new person to the address book.</p>
158: *
159: * @param securitySession Used to validate the current user can add the
160: * person.
161: * @param personDO data object containing the details of the
162: * person you want to add.
163: * @return the new person data object, with the details as they
164: * now are in the address book.
165: * @throws SystemException If the person cannot be added for any
166: * reason.
167: */
168: PersonDO addPerson(final SecuritySession securitySession,
169: final PersonDO personDO) throws SystemException;
170:
171: /**
172: * <p>Amend the details of a group in the address book.</p>
173: *
174: * @param securitySession Used to validate the current user can amend the
175: * group.
176: * @param groupDO a data object containing all the details
177: * of the group to amend.
178: * @return the new group data object, with the details as they
179: * now are in the address book.
180: * @throws SystemException If the group cannot be amended for any
181: * reason.
182: */
183: GroupDO amendGroup(final SecuritySession securitySession,
184: final GroupDO groupDO) throws SystemException;
185:
186: /**
187: * <p>Change/update a person's details in the addressbook.</p>
188: *
189: * @param securitySession Used to validate the current user can amend the
190: * person.
191: * @param personDO data object containing the details of the
192: * person you want to amend.
193: * @return the new person data object, with the details as they
194: * now are in the address book.
195: * @throws SystemException If the person cannot be amended for any
196: * reason.
197: */
198: PersonDO amendPerson(final SecuritySession securitySession,
199: final PersonDO personDO) throws SystemException;
200:
201: /**
202: * Get a list of all addressbooks in the system, which the current user
203: * has permissions to view.
204: *
205: * @param securitySession Used to filter the address books to only those the
206: * current user can see.
207: * @param includePersonal If <code>true</code>, the current user's personal
208: * address book will be included (otherwise it won't).
209: * @return all of the address books in the system as a <code>List</code>
210: * of {@link GroupDO} instances.
211: * @throws SystemException If there is any reason why the address books
212: * cannot be accessed.
213: */
214: List findAddressBooks(final SecuritySession securitySession,
215: final boolean includePersonal) throws SystemException;
216:
217: /**
218: * <p>Find all of the countries in the system.</p>
219: *
220: * @param securitySession Used to validate the current user is allowed to
221: * see this information.
222: * @return all of the countries in the system as a <code>List</code>
223: * of {@link CountryDO} instances.
224: * @throws SystemException If there is any reason why the countries
225: * cannot be accessed.
226: */
227: List findAllCountries(final SecuritySession securitySession)
228: throws SystemException;
229:
230: /**
231: * <p>Find All People in a specific address book (which the current security
232: * user is permitted to view).</p>
233: *
234: * @param securitySession Used to filter the people to only those the
235: * current user can see.
236: * @param group Parent group containing all the people to be retrieved.
237: * @param initialLetter If not <code>null</code>, specifies the initial
238: * letter of the person's <code>fileAs</code> field, to act as a filter.
239: * @return <code>List</code> containing instances of {@link PersonDO}.
240: * @throws SystemException If there is any reason why the people
241: * cannot be accessed.
242: */
243: List findAllPeopleInGroup(final SecuritySession securitySession,
244: final GroupDO group, final String initialLetter)
245: throws SystemException;
246:
247: /**
248: * <p>Find a single county identified by its two-letter country code.</p>
249: *
250: * @param securitySession Used to validate the current user is allowed to
251: * see this information.
252: * @param countryCode two-letter internet country code.
253: * @return details of the country as an instance of
254: * {@link CountryDO),
255: * or <code>null</code> if no such country exists.
256: * @throws SystemException If there is any reason why the country
257: * cannot be accessed.
258: */
259: CountryDO findCountryByCode(final SecuritySession securitySession,
260: final String countryCode) throws SystemException;
261:
262: /**
263: * <p>Find a group in the address book by its unique identifier.</p>
264: *
265: * @param securitySession Used to validate the current user is allowed to
266: * see this information.
267: * @param id the unique identifier of the group to find.
268: * @return the data object of the group which matches this unique
269: * identifier.
270: * @throws SystemException If there is any reason why the group
271: * cannot be accessed.
272: */
273: GroupDO findGroupByPrimaryKey(
274: final SecuritySession securitySession, final Integer id)
275: throws SystemException;
276:
277: /**
278: * <p>
279: * Find all groups which are siblings, identified by the parent group
280: * identifier.
281: * </p>
282: *
283: * @param securitySession Used to filter the groups to only those the
284: * current user can see.
285: * @param parentId Unique identifier of the parent group.
286: * @return <code>List</code> containing {@link GroupDO} instances of all
287: * groups contained within the given parent.
288: * @throws SystemException If the parent group cannot be found, or there
289: * is any reason why the groups cannot be accessed.
290: */
291: List findGroupsByParent(final SecuritySession securitySession,
292: final Integer parentId) throws SystemException;
293:
294: /**
295: * <p>Obtain an instance of personal address book.</p>
296: *
297: * @param securitySession Specifies the user for whom to find the current
298: * address book, and used to validate this user is allowed to see this.
299: * @return Personal address book group for the current user.
300: * @throws SystemException If there
301: * is any reason why the group cannot be accessed.
302: */
303: GroupDO findPersonalAddressBook(
304: final SecuritySession securitySession)
305: throws SystemException;
306:
307: /**
308: * <p>
309: * Find a person in the address book by her unique identifier.
310: * </p>
311: *
312: * @param securitySession Used to validate the current user is allowed to
313: * see this information.
314: * @param id The unique identifier of the person to find.
315: * @return The person data object which matches this id, with the
316: * details as they now are in the address book.
317: * @throws SystemException If there
318: * is any reason why the person cannot be accessed.
319: */
320: PersonDO findPersonByPrimaryKey(
321: final SecuritySession securitySession, final String id)
322: throws SystemException;
323:
324: /**
325: * <p>Find a person in the address book by her user name.</p>
326: *
327: * @param securitySession Used to validate the current user is allowed to
328: * see this information.
329: * @param userName Name of the user to find.
330: * @return The person data object which matches this user name.
331: * @throws SystemException If there
332: * is any reason why the person cannot be accessed.
333: */
334: PersonDO findPersonByUserName(
335: final SecuritySession securitySession, final String userName)
336: throws SystemException;
337:
338: /**
339: * <p>
340: * Remove a group from the system.
341: * </p>
342: *
343: * @param securitySession Used to validate the current user is allowed to
344: * perform this action.
345: * @param id Unique identifier of the group to be removed.
346: * @throws SystemException If there
347: * is any reason why the group cannot be removed.
348: */
349: void removeGroup(final SecuritySession securitySession,
350: final Integer id) throws SystemException;
351:
352: /**
353: * <p>Remove a person from the address book.</p>
354: *
355: * @param securitySession Used to validate the current user is allowed to
356: * perform this action.
357: * @param id Unique identifier of the person to be removed.
358: * @throws SystemException If there
359: * is any reason why the person cannot be removed.
360: */
361: void removePerson(final SecuritySession securitySession,
362: final Integer id) throws SystemException;
363:
364: /**
365: * <p>Confirm all of the elements of the address are present and valid.</p>
366: *
367: * @param securitySession Used to validate the current user is allowed to
368: * perform this action.
369: * @param addressDO Data object to check for consistency and
370: * completeness.
371: * @return A collection of validation errors if any of the
372: * mandatory fields are missing, or if fields contain invalid values.
373: * @throws SystemException If there
374: * is any reason why the address cannot be checked.
375: */
376: ValidationErrors validate(final SecuritySession securitySession,
377: final AddressDO addressDO) throws SystemException;
378:
379: /**
380: * <p>Confirm all of the elements of the group are present and valid.</p>
381: *
382: * @param securitySession Used to validate the current user is allowed to
383: * perform this action.
384: * @param groupDO data object to check for consistency and
385: * completeness.
386: * @return A collection of validation errors if any of the
387: * mandatory fields are missing, or if fields contain invalid values.
388: * @throws SystemException If there
389: * is any reason why the group cannot be checked.
390: */
391: ValidationErrors validate(final SecuritySession securitySession,
392: final GroupDO groupDO) throws SystemException;
393:
394: /**
395: * <p>Confirm all of the elements of the person are present and valid.</p>
396: *
397: * @param securitySession Used to validate the current user is allowed to
398: * perform this action.
399: * @param personDO data object to check for consistency and
400: * completeness.
401: * @return A collection of validation errors if any of the
402: * mandatory fields are missing, or if fields contain invalid values.
403: * @throws SystemException If there
404: * is any reason why the person cannot be checked.
405: */
406: ValidationErrors validate(final SecuritySession securitySession,
407: final PersonDO personDO) throws SystemException;
408: }
|