001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.lib.collab;
043:
044: /**
045: *
046: * The PersonalStore Service
047: * The service should be intialized by calling intialize() before using any
048: * of the methods.
049: *
050: * @since version 0.1
051: *
052: */
053: public interface PersonalStoreService {
054: /**
055: * retrieves a personal store entry from its entry id
056: * @param entryType entry type, as defined in PersonalStoreEntry
057: * @param entryId entry's unique id
058: * @return entry if found.
059: */
060: public PersonalStoreEntry getEntry(String entryType, String entryId)
061: throws CollaborationException;
062:
063: /**
064: * retrieves a personal store entry from its entry id
065: * @param entryType entry type, as defined in PersonalStoreEntry
066: * @param entryId entry's unique id
067: * @param principal owner of the personal store to query
068: * @return entry if found.
069: */
070: public PersonalStoreEntry getEntry(
071: CollaborationPrincipal principal, String entryType,
072: String entryId) throws CollaborationException;
073:
074: /**
075: * retrieves all entries of a specific type from the personal
076: * store
077: * note: this assumes there aren't too many folders in the personal store
078: * <p>
079: * note: retrieves only the folders, not the entries.
080: * @param entryType folderType type of folder as defined in PersonalStoreEntryType
081: * @return a Collection of PersonalStoreFolder objects
082: */
083: public java.util.Collection getEntries(String entryType)
084: throws CollaborationException;
085:
086: /**
087: * retrieves all the folders in the personal store
088: * note: this assumes there aren't too many folders in the personal store
089: * <p>
090: * note: retrieves only the folders, not the entries.
091: * @param entryType folderType type of folder as defined in PersonalStoreEntryType
092: * @return a Collection of PersonalStoreFolder objects
093: */
094: public java.util.Collection getFolders(String entryType)
095: throws CollaborationException;
096:
097: /**
098: * retrieves all the folders in the personal store of a specified principal
099: * note: this assumes there aren't too many folders in the personal store
100: * <p>
101: * note: retrieves only the folders, not the entries.
102: * @param principal owner of the personal store to query
103: * @param entryType folderType type of folder as defined in PersonalStoreEntryType
104: * @return a Collection of PersonalStoreFolder objects
105: */
106: public java.util.Collection getFolders(
107: CollaborationPrincipal principal, String entryType)
108: throws CollaborationException;
109:
110: /**
111: * creates a new entry
112: * This method does not necessarily commit the entry to permanent storage.
113: * The other attributes of the created entry need to be set using the
114: * methods in PersonalStoreEntry or subclass thereof. In particular,
115: * the folder(s) referencing this entry must be specified using
116: * PersonalStoreEntry.addToFolder().
117: * After the entry is complete, it must be committed with its save()
118: * method.
119: *
120: * @param entryType type of entry as defined in PersonalStoreEntryType
121: * @param displayName entry display name
122: * @return a new entry, which class depends on the specified type.
123: * Note that the returned entry may be a folder.
124: */
125: public PersonalStoreEntry createEntry(String entryType,
126: String displayName) throws CollaborationException;
127:
128: /**
129: * creates a new entry on behalf of a specified user
130: * This method does not necessarily commit the entry to permanent storage.
131: * The other attributes of the created entry need to be set using the
132: * methods in PersonalStoreEntry or subclass thereof. In particular,
133: * the folder(s) referencing this entry must be specified using
134: * PersonalStoreEntry.addToFolder().
135: * After the entry is complete, it must be committed with its save()
136: * method.
137: *
138: * @param principal owner ofd the personal store in which to add the
139: * new entry
140: * @param entryType type of entry as defined in PersonalStoreEntryType
141: * @param displayName entry display name
142: * @return a new entry, which class depends on the specified type.
143: * Note that the returned entry may be a folder.
144: */
145: public PersonalStoreEntry createEntry(
146: CollaborationPrincipal principal, String entryType,
147: String displayName) throws CollaborationException;
148:
149: /**
150: * search directory for entry
151: * This method search the corporate directory for entries that can then
152: * be used to add as a PersonalContact to the PersonalStoreFolder.
153: * There are four types of search criteria: BYUID, CONTAINNAME, STARTNAME,
154: * ENDNAME. When a particular one is choosed to be added to a folder,
155: * pass that as the argument to the createEntry() method.
156: *
157: * @param searchType type of search to perform
158: * @param pattern searchName name to search for
159: * @return a array of principals from the search result,
160: * or null if none matched
161: */
162: public CollaborationPrincipal[] searchPrincipals(int searchType,
163: String pattern) throws CollaborationException;
164:
165: /**
166: * search directory for entry
167: * This method search the corporate directory for entries that can
168: * then be used to add as a PersonalContact to the PersonalStoreFolder.
169: * There are four types of search criteria: BYUID, CONTAINNAME, STARTNAME,
170: * ENDNAME. When a particular one is choosed to be added to a folder,
171: * pass that as the argument to the createEntry() method.
172: * The attribute for the search can be NAME_ATTRIBUTE or UID_ATTRIBUTE
173: * or MAIL_ATTRIBUTE
174: *
175: * @param searchType type of search to perform
176: * @param pattern searchName name to search for
177: * @param attribute Attribute on which to search for
178: * @return a array of principals from the search result,
179: * or null if none matched
180: */
181: public CollaborationPrincipal[] searchPrincipals(int searchType,
182: String pattern, int attribute)
183: throws CollaborationException;
184:
185: /**
186: * search directory for entry
187: * This method search the corporate directory for entries that can then be
188: * used to add as a PersonalContact to the PersonalStoreFolder.
189: * There are four types of search criteria: BYUID, CONTAINNAME, STARTNAME,
190: * ENDNAME. When a particular one is choosed to be added to a folder,
191: * pass that as the argument to the createEntry() method.
192: *
193: * @param searchType type of search to perform
194: * @param pattern searchName name to search for
195: * @return a array of principals from the search result,
196: * or null if none matched
197: */
198: public PersonalStoreEntry[] search(int searchType, String pattern,
199: String entryType) throws CollaborationException;
200:
201: /**
202: * @param searchType type of search to perform
203: * @param pattern searchName name to search for
204: * @param entryType type of the entry to search for
205: * @param attribute Attribute on which to search for
206: * @return a array of principals from the search result,
207: * or null if none matched
208: */
209: public PersonalStoreEntry[] search(int searchType, String pattern,
210: String entryType, int attribute)
211: throws CollaborationException;
212:
213: /**
214: * get the profile info
215: *
216: * @return profile the profile info
217: */
218: public PersonalProfile getProfile() throws CollaborationException;
219:
220: /**
221: * get the profile info
222: *
223: * @param principal owner of the personal store to query
224: * @return profile the profile info
225: */
226: public PersonalProfile getProfile(CollaborationPrincipal principal)
227: throws CollaborationException;
228:
229: /**
230: * Commit unsaved personal store changes to the server
231: */
232: public void save() throws CollaborationException;
233:
234: /**
235: * intialize the service by providing a PersonalStoreServiceListener.
236: * Service should be initialized by calling this method before using
237: * any of the services of PersonalStoreService
238: * @param listener PersonalStoreServiceListener
239: */
240: public void initialize(PersonalStoreServiceListener listener)
241: throws CollaborationException;
242:
243: /**
244: * Add an additional PersonalStoreServiceListener to receive the event notifications.
245: * To receive all the initial events the first PersonalStoreServiceListener should be
246: * added while {@link #initialize initializing} PersonalStoreService.
247: * @param listener PersonalStoreServiceListener The PersonalStoreServiceListener to be added.
248: */
249: public void addPersonalStoreServiceListener(
250: PersonalStoreServiceListener listener);
251:
252: /**
253: * Removes an already added ConfereneServiceListener. To prevent loss of any event
254: * notification it is advised to have atleast one PersonalStoreServiceListener
255: * @param listener PersonalStoreServiceListener The PersonalStoreServiceListener to be removed.
256: */
257: public void removePersonalStoreServiceListener(
258: PersonalStoreServiceListener listener);
259:
260: /*
261: //valid result is returned but there may be more that were past the limit
262: public static final int SEARCH_LIMIT_EXCEEDED = 1;
263:
264: //normal returned results
265: public static final int SEARCH_OK = 2;
266:
267: //the argument (filter) to use for the search was invalid
268: public static final int SEARCH_BAD_ARGUMENT = 3;
269:
270: //search has been disabled
271: public static final int SEARCH_DISABLED = 4;
272:
273: //an error has occured and we dont know why
274: public static final int SEARCH_ERROR = 5;
275: */
276:
277: // ----------------------------- //
278: // pre-defined search criteria //
279: // ----------------------------- //
280: /**
281: * search by contain name
282: */
283: public static final int SEARCHTYPE_CONTAINS = 1;
284:
285: /**
286: * search by start with name
287: */
288: public static final int SEARCHTYPE_STARTSWITH = 2;
289:
290: /**
291: * search by end with name
292: */
293: public static final int SEARCHTYPE_ENDSWITH = 3;
294:
295: /**
296: * equals
297: */
298: public static final int SEARCHTYPE_EQUALS = 0;
299:
300: /**
301: * search on name attribute
302: */
303: public static final int NAME_ATTRIBUTE = 1;
304:
305: /**
306: * search on uid attribute
307: */
308: public static final int UID_ATTRIBUTE = 2;
309:
310: /**
311: * search on mail attribute
312: */
313: public static final int MAIL_ATTRIBUTE = 4;
314: }
|