001: /***
002: * jwma Java WebMail
003: * Copyright (c) 2000-2003 jwma team
004: *
005: * jwma is free software; you can distribute and use this source
006: * under the terms of the BSD-style license received along with
007: * the distribution.
008: ***/package dtw.webmail.plugin;
009:
010: import dtw.webmail.model.JwmaContactsImpl;
011: import dtw.webmail.model.JwmaException;
012: import dtw.webmail.model.JwmaContact;
013: import dtw.webmail.model.JwmaContacts;
014:
015: import java.io.InputStream;
016: import java.io.OutputStream;
017:
018: /**
019: * Interface for a plugin that manages
020: * user contact databases.<p>
021: *
022: * @author Dieter Wimberger
023: * @version 0.9.7 07/02/2003
024: */
025: public interface ContactManagementPlugin extends JwmaPlugin {
026:
027: /**
028: * Loads the given contacts database from the
029: * persistent store and returns them as a <tt>
030: * JwmaContactsImpl</tt> instance.
031: * <p>
032: * If contacts database with the given identity does not
033: * exist on the store, the method returns <tt>null</tt>.
034: *
035: * @param cuid a <tt>String</tt> representing a unique
036: * identifier for a contact database.
037: *
038: * @return the <tt>JwmaContactsImpl</tt> instance.
039: *
040: * @throws JwmaException if an I/O error occurs.
041: *
042: * @see dtw.webmail.model.JwmaContactsImpl
043: * @see dtw.webmail.model.JwmaPreferencesImpl#getContactDatabaseID()
044: */
045: public JwmaContactsImpl loadContacts(String cuid)
046: throws JwmaException;
047:
048: /**
049: * Saves the given contacts database to the persistent store.
050: * <p>
051: * If the contacts database does not exist on the store,
052: * the method should create it, otherwise update
053: * the existing version.<br>
054: * The unique identity is retrieved using the <tt>getUID()</tt>
055: * method of the given <tt>JwmaContactsImpl</tt> instance.
056: *
057: * @param contacts the <tt>JwmaContactsImpl</tt> instance to
058: * saved.
059: *
060: * @throws JwmaException if an I/O error occurs.
061: *
062: * @see dtw.webmail.model.JwmaContactsImpl
063: * @see dtw.webmail.model.JwmaContactsImpl#getUID()
064: */
065: public void saveContacts(JwmaContactsImpl contacts)
066: throws JwmaException;
067:
068: /**
069: * Tests if a given contact database exists
070: * on the store.
071: *
072: * @param cuid a <tt>String</tt> representing a unique
073: * identifier for a contact database.
074: *
075: * @throws JwmaException if an I/O error occurs.
076: *
077: * @see dtw.webmail.model.JwmaContactsImpl
078: * @see dtw.webmail.model.JwmaPreferencesImpl#getContactDatabaseID()
079: */
080: public boolean isPersistent(String cuid) throws JwmaException;
081:
082: /**
083: * Creates a new contact databse instance.
084: *
085: * @return the <tt>JwmaContactsImpl</tt> instance.
086: *
087: * @see dtw.webmail.model.JwmaContactsImpl
088: */
089: public JwmaContactsImpl createContacts();
090:
091: /**
092: * Exports a contact in the given type.
093: *
094: * @param contact the <tt>JwmaContact</tt> to be exported.
095: * @param TYPE the type of the export.
096: *
097: * @return the exported contact as <tt>String</tt>.
098: *
099: * @see #getSupportedTypes(int IMEX_TYPE)
100: * @see #CONTACT_EXPORT
101: */
102: public String exportContact(JwmaContact contact, String TYPE)
103: throws JwmaException;
104:
105: /**
106: * Imports a contact of the given type.
107: *
108: * @param in source for importing the contact in the given type.
109: * @param TYPE the type of the import source.
110: *
111: * @return the imported contact as <tt>JwmaContact</tt>.
112: *
113: * @see #getSupportedTypes(int IMEX_TYPE)
114: * @see #CONTACT_IMPORT
115: */
116: public JwmaContact importContact(InputStream in, String TYPE)
117: throws JwmaException;
118:
119: /**
120: * Exports the given contact database in the given type.
121: *
122: * @param the <tt>OutputStream</tt> to export to.
123: * @param db the <tt>JwmaContacts</tt> database to be exported.
124: * @param TYPE the type of the export.
125: *
126: *
127: * @see #getSupportedTypes(int IMEX_TYPE)
128: * @see #DATABASE_EXPORT
129: */
130: public void exportDatabase(OutputStream out, JwmaContacts db,
131: String TYPE) throws JwmaException;
132:
133: /**
134: * Imports a database of contacts of the given type.
135: *
136: * @param in source for importing the contacts in the given type.
137: * @param TYPE the type of the import source.
138: *
139: * @return the imported contacts as <tt>JwmaContact[]</tt>.
140: *
141: * @see #getSupportedTypes(int IMEX_TYPE)
142: * @see #DATABASE_IMPORT
143: */
144: public JwmaContact[] importDatabase(InputStream in, String Type)
145: throws JwmaException;
146:
147: /**
148: * Returns a list of types for the given import/export method.
149: * The types from this array can be passed as parameters
150: * to the respective import/export method.
151: *
152: * @return an array of <tt>String</tt>'s representing types.
153: */
154: public String[] getSupportedTypes(int IMEX_TYPE);
155:
156: /**
157: * Tests if the given contact type can be imported.
158: *
159: * @return true if supported, false otherwise.
160: */
161: public boolean isSupportedContactImportType(String type);
162:
163: public static final int CONTACT_EXPORT = 0;
164: public static final int CONTACT_IMPORT = 1;
165: public static final int DATABASE_EXPORT = 2;
166: public static final int DATABASE_IMPORT = 3;
167:
168: }//interface ContactManagementPlugin
|