JAMES-2425 Make MailRepositoryStore javadoc more explicit for get* methods
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/c3715e70 Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/c3715e70 Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/c3715e70 Branch: refs/heads/master Commit: c3715e7083fbe025cf98ec326afcbffe2f93848d Parents: a171024 Author: benwa <[email protected]> Authored: Thu Aug 2 16:13:15 2018 +0700 Committer: Benoit Tellier <[email protected]> Committed: Fri Aug 3 07:57:22 2018 +0700 ---------------------------------------------------------------------- .../mailrepository/api/MailRepositoryStore.java | 36 ++++++++++++++------ 1 file changed, 25 insertions(+), 11 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/james-project/blob/c3715e70/server/data/data-api/src/main/java/org/apache/james/mailrepository/api/MailRepositoryStore.java ---------------------------------------------------------------------- diff --git a/server/data/data-api/src/main/java/org/apache/james/mailrepository/api/MailRepositoryStore.java b/server/data/data-api/src/main/java/org/apache/james/mailrepository/api/MailRepositoryStore.java index babc19c..7d0c520 100644 --- a/server/data/data-api/src/main/java/org/apache/james/mailrepository/api/MailRepositoryStore.java +++ b/server/data/data-api/src/main/java/org/apache/james/mailrepository/api/MailRepositoryStore.java @@ -25,17 +25,18 @@ import java.util.stream.Stream; public interface MailRepositoryStore { /** - * Select the {@link MailRepository} for the given url. Repository will be created if it does not exist already. - * - * @param url - * @return repository - * @throws MailRepositoryStoreException + * Select the {@link MailRepository} for the given url. + * + * If the repository is not referenced by {@link MailRepositoryStore::getUrls}, it will be created, and its URL referenced + * by {@link MailRepositoryStore::getUrls}. */ MailRepository select(MailRepositoryUrl url) throws MailRepositoryStoreException; /** * Create the {@link MailRepository} for the given url and return it. If the repository already exists, * then no new repository is created, the old one will be returned. + * + * The URL of the created repository will be referenced by {@link MailRepositoryStore::getUrls} */ default MailRepository create(MailRepositoryUrl url) throws MailRepositoryStoreException { return select(url); @@ -43,24 +44,37 @@ public interface MailRepositoryStore { /** * Returns the {@link MailRepository} for the given url. - * This mail repository will not be created if it does not exist. + * + * This mail repository will not be created if the URL is not referenced by {@link MailRepositoryStore::getUrls}. + * + * If the repository is referenced by {@link MailRepositoryStore::getUrls}, and the repository do not exist locally, then + * this repository will be created locally. */ Optional<MailRepository> get(MailRepositoryUrl url) throws MailRepositoryStoreException; /** - * Returns all the {@link MailRepository} for the given path. + * Returns all the {@link MailRepository} referenced by {@link MailRepositoryStore::getUrls} got a given path. + * + * The corresponding mail repositories will not be created if they do not exist. + * + * If the path matches URLs referenced by {@link MailRepositoryStore::getUrls}, and the repositories do not exist locally, then + * these repositories will be created locally. */ Stream<MailRepository> getByPath(MailRepositoryPath path) throws MailRepositoryStoreException; /** - * Return a {@link Stream} which contains all urls of the selected - * {@link MailRepository}'s + * Return a {@link Stream} which contains all urls of the selected {@link MailRepository}'s. + * + * Note that this may include MailRepositories that do not exist locally. + * + * This can be the case if: + * - The MailRepository had been created by another James server in a clustered environment + * - The MailRepository had been dynamically created, and James was restarted */ Stream<MailRepositoryUrl> getUrls(); /** - * Return a {@link Stream} which contains all paths of the selected - * {@link MailRepository}'s + * Return a {@link Stream} which contains all paths of the selected {@link MailRepository}'s */ default Stream<MailRepositoryPath> getPaths() { return getUrls() --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
