You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by pg...@apache.org on 2002/08/17 00:00:09 UTC
cvs commit: jakarta-james/src/java/org/apache/james/services DNSServer.java JamesUser.java MailRepository.java MailServer.java MailStore.java SpoolRepository.java User.java UsersRepository.java UsersStore.java
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 <ha...@kodemuse.com>
*/
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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>