pgoldstein 2002/08/16 15:00:07 Modified: src/java/org/apache/james/services DNSServer.java JamesUser.java MailRepository.java MailServer.java MailStore.java SpoolRepository.java User.java UsersRepository.java UsersStore.java Log: Added extensive comments. Revision Changes Path 1.4 +11 -13 jakarta-james/src/java/org/apache/james/services/DNSServer.java Index: DNSServer.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/services/DNSServer.java,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- DNSServer.java 24 Sep 2001 17:25:45 -0000 1.3 +++ DNSServer.java 16 Aug 2002 22:00:06 -0000 1.4 @@ -8,30 +8,28 @@ package org.apache.james.services; import java.util.Collection; -//import org.xbill.DNS.Record; /** * Provides abstraction for DNS resolutions. The interface is Mail specific. * It may be a good idea to make the interface more generic or expose * commonly needed DNS methods. + * * @author Harmeet <[EMAIL PROTECTED]> */ public interface DNSServer { + + /** + * The component role used by components implementing this service + */ String ROLE = "org.apache.james.services.DNSServer"; - /** + /** + * <p>Get a priority-sorted collection of DNS MX records for a given hostname</p> + * + * <p>TODO: Change this to a list, as not all collections are sortable</p> + * + * @param hostname the hostname to check * @return collection of strings representing MX record values. - * The returned collection is sorted by priority. */ Collection findMXRecords(String hostname); - - /** @param name : query name, - * @param type : Record type. @param type is expected to be one of the - * types defined in org.xbill.DNS.Type - */ - // I thought this was a good general method to expose :-) - // but it ties the interface to xbill library.:-( - // the interface should be neutral and implementation replaceable. - // one way is to have a DNSRecord abstraction... - //Record[] lookup(String name, short type); } 1.3 +13 -6 jakarta-james/src/java/org/apache/james/services/JamesUser.java Index: JamesUser.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/services/JamesUser.java,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- JamesUser.java 30 Jul 2002 10:38:35 -0000 1.2 +++ JamesUser.java 16 Aug 2002 22:00:07 -0000 1.3 @@ -21,13 +21,18 @@ public interface JamesUser extends User { /** - * Change password to pass. Return true if uccessful. + * Change password to pass. Return true if successful. + * + * @param pass the new password + * @return true if successful, false otherwise */ boolean setPassword(String pass); /** * Indicate if mail for this user should be forwarded to some other mail * server. + * + * @param forward whether email for this user should be forwarded */ void setForwarding(boolean forward); @@ -37,8 +42,10 @@ boolean getForwarding(); /** - * Set destination for forwading mail - * Should we use a MailAddress? + * <p>Set destination for forwading mail</p> + * <p>TODO: Should we use a MailAddress?</p> + * + * @param address the forwarding address for this user */ boolean setForwardingDestination(MailAddress address); @@ -54,7 +61,7 @@ void setAliasing(boolean alias); /** - * Return true if emails should be dlivered locally to an alias. + * Return true if emails should be delivered locally to an alias. */ boolean getAliasing(); 1.4 +19 -0 jakarta-james/src/java/org/apache/james/services/MailRepository.java Index: MailRepository.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/services/MailRepository.java,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- MailRepository.java 18 Jan 2002 02:48:37 -0000 1.3 +++ MailRepository.java 16 Aug 2002 22:00:07 -0000 1.4 @@ -29,38 +29,57 @@ /** * Stores a message in this repository. Shouldn't this return the key * under which it is stored? + * + * @param mc the mail message to store */ void store(MailImpl mc); /** * List string keys of messages in repository. * + * @return an <code>Iterator</code> over the list of keys in the repository + * */ Iterator list(); /** * Retrieves a message given a key. At the moment, keys can be obtained * from list() in superinterface Store.Repository + * + * @param key the key of the message to retrieve + * @return the mail corresponding to this key, null if none exists */ MailImpl retrieve(String key); /** * Removes a specified message + * + * @param mail the message to be removed from the repository */ void remove(MailImpl mail); /** * Removes a message identified by key. + * + * @param key the key of the message to be removed from the repository */ void remove(String key); /** * Obtains a lock on a message identified by key + * + * @param key the key of the message to be locked + * + * @return true if successfully obtained the lock, false otherwise */ boolean lock(String key); /** * Releases a lock on a message identified the key + * + * @param key the key of the message to be unlocked + * + * @return true if successfully released the lock, false otherwise */ boolean unlock(String key); } 1.9 +10 -2 jakarta-james/src/java/org/apache/james/services/MailServer.java Index: MailServer.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/services/MailServer.java,v retrieving revision 1.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- MailServer.java 30 Jul 2002 10:38:35 -0000 1.8 +++ MailServer.java 16 Aug 2002 22:00:07 -0000 1.9 @@ -26,6 +26,9 @@ */ public interface MailServer { + /** + * The component role used by components implementing this service + */ String ROLE = "org.apache.james.services.MailServer"; /** @@ -83,6 +86,11 @@ */ MailRepository getUserInbox(String userName); + /** + * Generate a new identifier/name for a mail being processed by this server. + * + * @return the new identifier + */ String getId(); /** 1.4 +5 -2 jakarta-james/src/java/org/apache/james/services/MailStore.java Index: MailStore.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/services/MailStore.java,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- MailStore.java 6 Sep 2001 13:19:32 -0000 1.3 +++ MailStore.java 16 Aug 2002 22:00:07 -0000 1.4 @@ -29,6 +29,9 @@ public interface MailStore extends Store { + /** + * The component role used by components implementing this service + */ String ROLE = "org.apache.james.services.MailStore"; // MailRepository getInbox(String user); 1.2 +7 -3 jakarta-james/src/java/org/apache/james/services/SpoolRepository.java Index: SpoolRepository.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/services/SpoolRepository.java,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- SpoolRepository.java 11 May 2001 09:39:34 -0000 1.1 +++ SpoolRepository.java 16 Aug 2002 22:00:07 -0000 1.2 @@ -26,17 +26,21 @@ /** * Returns the key for an arbitrarily selected mail deposited in this Repository. - * Useage: SpoolManager calls accept() to see if there are any unprocessed + * Usage: SpoolManager calls accept() to see if there are any unprocessed * mails in the spool repository. + * + * @return the key for the mail */ String accept(); /** - * Returns the key for an arbitrarily select mail depository in this Repositry that + * Returns the key for an arbitrarily select mail deposited in this Repository that * is either ready immediately for delivery, or is younger than it's last_updated plus * the number of failed attempts times the delay time. - * Useage: RemoteDeliverySpool calls accept() with some delay and should block until an + * Usage: RemoteDeliverySpool calls accept() with some delay and should block until an * unprocessed mail is available. + * + * @return the key for the mail */ String accept(long delay); } 1.4 +7 -2 jakarta-james/src/java/org/apache/james/services/User.java Index: User.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/services/User.java,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- User.java 30 Jul 2002 10:38:35 -0000 1.3 +++ User.java 16 Aug 2002 22:00:07 -0000 1.4 @@ -20,11 +20,16 @@ /** * Return the user name of this user + * + * @return the user name for this user */ String getUserName(); /** * Return true if pass matches password of this user. + * + * @param pass the password to test + * @return whether the password being tested is valid */ boolean verifyPassword(String pass); 1.5 +35 -2 jakarta-james/src/java/org/apache/james/services/UsersRepository.java Index: UsersRepository.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/services/UsersRepository.java,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- UsersRepository.java 30 Jul 2002 10:38:35 -0000 1.4 +++ UsersRepository.java 16 Aug 2002 22:00:07 -0000 1.5 @@ -23,6 +23,9 @@ */ public interface UsersRepository { + /** + * The component role used by components implementing this service + */ String ROLE = "org.apache.james.services.UsersRepository"; String USER = "USER"; @@ -30,6 +33,8 @@ /** * Adds a user to the repository with the specified User object. * + * @param user the user to be added + * * @return true if succesful, false otherwise * @since James 1.2.2 */ @@ -38,6 +43,9 @@ /** * Adds a user to the repository with the specified attributes. In current * implementations, the Object attributes is generally a String password. + * + * @param name the name of the user to be added + * @param attributes see decription */ void addUser(String name, Object attributes); @@ -53,6 +61,9 @@ * Get the user object with the specified user name. Return null if no * such user. * + * @param name the name of the user to retrieve + * @return the user being retrieved, null if the user doesn't exist + * * @since James 1.2.2 */ User getUserByName(String name); @@ -61,6 +72,9 @@ * Get the user object with the specified user name. Match user naems on * a case insensitive basis. Return null if no such user. * + * @param name the name of the user to retrieve + * @return the user being retrieved, null if the user doesn't exist + * * @since James 1.2.2 */ User getUserByNameCaseInsensitive(String name); @@ -68,6 +82,9 @@ /** * Returns the user name of the user matching name on an equalsIgnoreCase * basis. Returns null if no match. + * + * @param name the name to case-correct + * @return the case-correct name of the user, null if the user doesn't exist */ String getRealName(String name); @@ -81,17 +98,25 @@ /** * Removes a user from the repository + * + * @param name the user to remove from the repository */ void removeUser(String name); /** * Returns whether or not this user is in the repository + * + * @param name the name to check in the repository + * @return whether the user is in the repository */ boolean contains(String name); /** * Returns whether or not this user is in the repository. Names are * matched on a case insensitive basis. + * + * @param name the name to check in the repository + * @return whether the user is in the repository */ boolean containsCaseInsensitive(String name); @@ -108,12 +133,20 @@ /** * Test if user with name 'name' has password 'password'. * + * @param name the name of the user to be tested + * @param password the password to be tested + * + * @return true if the test is successful, false if the user + * doesn't exist or if the password is incorrect + * * @since James 1.2.2 */ boolean test(String name, String password); /** * Returns a count of the users in the repository. + * + * @return the number of users in the repository */ int countUsers(); 1.6 +16 -2 jakarta-james/src/java/org/apache/james/services/UsersStore.java Index: UsersStore.java =================================================================== RCS file: /home/cvs/jakarta-james/src/java/org/apache/james/services/UsersStore.java,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- UsersStore.java 17 Jan 2002 06:09:02 -0000 1.5 +++ UsersStore.java 16 Aug 2002 22:00:07 -0000 1.6 @@ -20,13 +20,27 @@ */ public interface UsersStore { + /** + * The component role used by components implementing this service + */ String ROLE = "org.apache.james.services.UsersStore"; + /** + * Get the repository, if any, whose name corresponds to + * the argument parameter + * + * @param name the name of the desired repository + * + * @return the UsersRepository corresponding to the name parameter + */ UsersRepository getRepository( String name ); /** - * @return repository names that could be resolved by - * calling 'getRepository' method + * Yield an <code>Iterator</code> over the set of repository + * names managed internally by this store. + * + * @return an Iterator over the set of repository names + * for this store */ Iterator getRepositoryNames(); }
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>