AddressBook


1   /*
2    * Copyright (c) 2001 - 2005 ivata limited.
3    * All rights reserved.
4    * -----------------------------------------------------------------------------
5    * ivata groupware may be redistributed under the GNU General Public
6    * License as published by the Free Software Foundation;
7    * version 2 of the License.
8    *
9    * These programs are free software; you can redistribute them and/or
10   * modify them under the terms of the GNU General License
11   * as published by the Free Software Foundation; version 2 of the License.
12   *
13   * These programs are distributed in the hope that they will be useful,
14   * but WITHOUT ANY WARRANTY; without even the implied warranty of
15   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16   *
17   * See the GNU General License in the file LICENSE.txt for more
18   * details.
19   *
20   * If you would like a copy of the GNU General License write to
21   *
22   * Free Software Foundation, Inc.
23   * 59 Temple Place - Suite 330
24   * Boston, MA 02111-1307, USA.
25   *
26   *
27   * To arrange commercial support and licensing, contact ivata at
28   *                  http://www.ivata.com/contact.jsp
29   * -----------------------------------------------------------------------------
30   * $Log: AddressBook.java,v $
31   * Revision 1.4  2005/04/29 02:48:14  colinmacleod
32   * Data bugfixes.
33   * Changed primary key back to Integer.
34   *
35   * Revision 1.3  2005/04/10 20:09:33  colinmacleod
36   * Added new themes.
37   * Changed id type to String.
38   * Changed i tag to em and b tag to strong.
39   * Improved PicoContainerFactory with NanoContainer scripts.
40   *
41   * Revision 1.2  2005/04/09 17:19:06  colinmacleod
42   * Changed copyright text to GPL v2 explicitly.
43   *
44   * Revision 1.1.1.1  2005/03/10 17:50:18  colinmacleod
45   * Restructured ivata op around Hibernate/PicoContainer.
46   * Renamed ivata groupware.
47   *
48   * Revision 1.5  2004/11/12 18:17:10  colinmacleod
49   * Ordered imports.
50   *
51   * Revision 1.4  2004/11/12 15:56:47  colinmacleod
52   * Removed dependencies on SSLEXT.
53   * Moved Persistence classes to ivata masks.
54   *
55   * Revision 1.3  2004/07/18 21:59:12  colinmacleod
56   * Removed Person from User - now you need to use addressbook/persistence
57   * manager to find the person (makes the app run faster.)
58   *
59   * Revision 1.2  2004/07/13 19:41:13  colinmacleod
60   * Moved project to POJOs from EJBs.
61   * Applied PicoContainer to services layer (replacing session EJBs).
62   * Applied Hibernate to persistence layer (replacing entity EJBs).
63   *
64   * Revision 1.1  2004/03/26 21:34:35  colinmacleod
65   * Split off functionality into POJO.
66   * -----------------------------------------------------------------------------
67   */
68  package com.ivata.groupware.business.addressbook;
69  
70  import java.util.List  ;
71  
72  import com.ivata.groupware.admin.security.server.SecuritySession;
73  import com.ivata.groupware.business.addressbook.address.AddressDO;
74  import com.ivata.groupware.business.addressbook.address.country.CountryDO;
75  import com.ivata.groupware.business.addressbook.person.PersonDO;
76  import com.ivata.groupware.business.addressbook.person.group.GroupDO;
77  import com.ivata.mask.util.SystemException;
78  import com.ivata.mask.validation.ValidationErrors;
79  
80  
81  /**
82   * @author Colin MacLeod
83   * <a HREF='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
84   * @since Mar 22, 2004
85   * @version $Revision: 1.4 $
86   */
87  public interface AddressBook {
88      public final static String   BUNDLE_PATH = "addressBook";
89      /**
90       * <p>Add bew AddressBook.</p>
91       * @param userName
92       * @param groupDO
93       * @return
94       */
95      GroupDO addAddressBook(final SecuritySession securitySession,
96              final GroupDO groupDO)
97          throws SystemException;
98  
99      /**
100      * <p>Add a new group to the address book.</p>
101      *
102      * @param userName the name of the user who wants to add the group. This is
103      *     used to check user rights.
104      * @param groupDO a data object containing all the details
105      *     of the group to add.
106      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
107      *     provided is not entitled to add this group
108      * @exception com.ivata.groupware.ejb.entity.InvalidFieldValueException
109      *     if a field value in the new group contains an invalid value
110      * @return the new group data object, with the details as they
111      *     now are in the adressbook.
112      */
113     GroupDO addGroup(final SecuritySession securitySession,
114             final GroupDO groupDO)
115             throws SystemException;
116 
117     /**
118      * <p>Add a new person to the address book.</p>
119      *
120      * @param personDO data object containing the details of the
121      *     person you want to add.
122      * @return the new person data object, with the details as they
123      *     now are in the adressbook.
124      */
125     PersonDO addPerson(final SecuritySession securitySession,
126             final PersonDO personDO)
127             throws SystemException;
128     /**
129      * <p>add new userGroup.</p>
130      * @param userName
131      * @param groupDO
132      * @return
133      */
134     GroupDO addUserGroup(final SecuritySession securitySession,
135             final GroupDO groupDO)
136         throws SystemException;
137 
138     /**
139      * <p>Amend the details of a group in the address book.</p>
140      *
141      * @param userName the name of the user who wants to amend the group. This
142      *     is used to check user rights.
143      * @param groupDO a data object containing all the details
144      *     of the group to amend.
145      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
146      *     provided is not entitled to amend this group.
147      * @exception com.ivata.groupware.ejb.entity.InvalidFieldValueException
148      *     if a field value in the new group contains an invalid value.
149      * @return the new group data object, with the details as they
150      *     now are in the adressbook.
151      */
152     GroupDO amendGroup(final SecuritySession securitySession,
153             final GroupDO groupDO)
154         throws SystemException;
155 
156     /**
157      * <p>Change/update a person's details in the addressbook.</p>
158      *
159      * @param personDO data object containing the details of the
160      *     person you want to amend.
161      * @return the new person data object, with the details as they
162      *     now are in the adressbook.
163      */
164     PersonDO amendPerson(final SecuritySession securitySession,
165             final PersonDO personDO)
166         throws SystemException;
167 
168     /**
169      * <p>get Map of all address book names which are allowed with specific access.</p>
170      * @param userName
171      * @param access
172      * @return
173      */
174     List   findAddressBooks(final SecuritySession securitySession,
175             final boolean includePersonal)
176         throws SystemException;
177 
178     /**
179      * <p>Find all of the countries in the system.</p>
180      *
181      * @return all of the coutries in the system as a <code>List</code>
182      * of {@link com.ivata.groupware.business.addressbook.address.country.CountryDO CountryDO}
183      * instances.
184      */
185     List   findAllCountries(final SecuritySession securitySession)
186         throws SystemException;
187 
188     /**
189      * <p>Find All People in a specific address book.</p
190      *
191      * @see com.ivata.groupware.business.addressbook.AddressBook#findAllPeople(com.ivata.groupware.admin.security.server.SecuritySession, Integer, Integer, String)
192      */
193     List   findAllPeopleInGroup(final SecuritySession securitySession,
194             final GroupDO group,
195             final String   initialLetter) throws SystemException;
196 
197     /**
198      * <p>Find a single county identified by its two-letter country code.</p>
199      *
200      * @param countryCode two-letter internet country code.
201      * @return details of the country as an instance of
202      * {@link com.ivata.groupware.business.addressbook.address.country.CountryDO CountryDO),
203      * or <code>null</code> if no such country exists.
204      */
205     CountryDO findCountryByCode(final SecuritySession securitySession,
206             final String   countryCode)
207         throws SystemException;
208 
209     /**
210      * <p>Find a group in the address book by its unique identifier.</p>
211      *
212      * @param id the unique identifier of the group to find.
213      * @return the data object of the group which matches this unique
214      *      identifier.
215      */
216     GroupDO findGroupByPrimaryKey(final SecuritySession securitySession,
217             final Integer   id)
218         throws SystemException;
219 
220     /**
221      * <p>
222      * Find all groups which are siblings, identified by the parent group.
223      * </p>
224      */
225     List   findGroupsByParent(final SecuritySession securitySession,
226             final Integer   parentId)
227             throws SystemException;
228 
229     /**
230      * <p>Find Id of personal AddressBook.</p>
231      * @param userName
232      * @return
233      */
234     GroupDO findPersonalAddressBook(final SecuritySession securitySession)
235         throws SystemException;
236 
237     /**
238      * <p>Find a person in the address book by their unique identifier.</p>
239      *
240      * @param id the unique identifier of the person to find.
241      * @return the person data object which matches this id, with the
242      *      details as they now are in the adressbook.
243      */
244     PersonDO findPersonByPrimaryKey(final SecuritySession securitySession,
245             final String   id)
246         throws SystemException;
247 
248     /**
249      * <p>Find a person in the address book by their user name.</p>
250      *
251      * @param userName Name of the user to find.
252      * @return the person data object which matches this user name.
253      */
254     PersonDO findPersonByUserName(final SecuritySession securitySession,
255             final String   userName)
256         throws SystemException;
257 
258     /**
259      * <p>get Map of all usergroup names which are allowed with specific access.</p>
260      * @param userName
261      * @param access
262      * @return
263      */
264     List   findUserGroups(final SecuritySession securitySession,
265             final boolean includeAdministrator)
266         throws SystemException;
267 
268     /**
269      * <p>Remove a group from the address book.</p>
270      *
271      * @param userName the name of the user who wants to remove the group. This
272      *     is used to check user rights.
273      * @param groupDO a data object containing all the details
274      *     of the group to remove. The id of the group is used to identify which
275      *      group to remove.
276      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
277      *     provided is not entitled to remvoe this group.
278      * @exception com.ivata.groupware.ejb.entity.InvalidFieldValueException
279      *     if the id of the group contains an invalid value.
280      */
281     void removeGroup(final SecuritySession securitySession,
282             final Integer   id)
283         throws SystemException;
284 
285     /**
286      * <p>Remove a person from the address book.</p>
287      *
288      * @param personDO data object containing the details of the
289      *     person you want to remove. The id is used to locate and remove the
290      *     person.
291      */
292     void removePerson(final SecuritySession securitySession,
293             final Integer   id)
294             throws SystemException;
295 
296     /**
297      * <p>Confirm all of the elements of the group are present and valid,
298      * before the message is sent.</p>
299      *
300      * @param groupDO data object to check for consistency and
301      *     completeness.
302      * @return a collection of validation errors if any of the
303      *     mandatory fields are missing, or if fields contain invalid values.
304      */
305     ValidationErrors validate(final SecuritySession securitySession,
306             final AddressDO addressDO)
307         throws SystemException;
308 
309      /**
310       * <p>Confirm all of the elements of the group are present and valid,
311       * before the message is sent.</p>
312       *
313       * @param groupDO data object to check for consistency and
314       *     completeness.
315       * @return a collection of validation errors if any of the
316       *     mandatory fields are missing, or if fields contain invalid values.
317       */
318      ValidationErrors validate(final SecuritySession securitySession,
319             final GroupDO groupDO)
320          throws SystemException;
321 
322     /**
323      * <p>Confirm all of the elements of the person are present and valid,
324      * before the message is sent.</p>
325      *
326      * @param personDO data object to check for consistency and
327      *     completeness.
328      * @return a collection of validation errors if any of the
329      *     mandatory fields are missing, or if fields contain invalid values.
330      */
331     ValidationErrors validate(final SecuritySession securitySession,
332             final PersonDO personDO)
333         throws SystemException;
334 }
335
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags