001package co.codewizards.cloudstore.core.repo.transport;
002
003import java.net.URL;
004import java.util.UUID;
005
006/**
007 * Factory creating instances of classes implementing {@link RepoTransport}.
008 * <p>
009 * <b>Important:</b> Implementors should <i>not</i> implement this interface directly. Instead,
010 * {@link AbstractRepoTransportFactory} should be sub-classed.
011 * @author Marco หงุ่ยตระกูล-Schulze - marco at codewizards dot co
012 */
013public interface RepoTransportFactory {
014
015        /**
016         * Gets the priority of this factory.
017         * <p>
018         * Factories are sorted primarily by this priority (descending). Thus, the greater the priority as a number
019         * the more likely it will be used.
020         * <p>
021         * Or in other words: The factory with the highest priority is chosen.
022         * <p>
023         * The default implementation in {@link AbstractRepoTransportFactory} returns 0. Thus, if you implement your
024         * own factory and register it for a URL type that is already handled by another factory,
025         * you must return a number greater than the other factory's priority (i.e. usually &gt 0).
026         * @return the priority of this factory.
027         */
028        int getPriority();
029
030        /**
031         * Gets the human-readable short name of this factory.
032         * <p>
033         * This should be a very short name like "File", "REST", "SOAP", etc. to be listed in a
034         * combo box or similar UI element.
035         * @return the human-readable short name of this factory. May be <code>null</code>, but
036         * implementors are highly discouraged to return <code>null</code> (or an empty string)!
037         * @see #getDescription()
038         */
039        String getName();
040
041        /**
042         * Gets the human-readable long description of this factory.
043         * <p>
044         * In contrast to {@link #getName()}, this method should provide an elaborate decription. It may be
045         * composed of multiple complete sentences and it may contain line breaks.
046         * @return the human-readable long description of this factory.  May be <code>null</code>. But
047         * implementors are encouraged to provide a meaningful description.
048         * @see #getName()
049         */
050        String getDescription();
051
052        /**
053         * Determine, whether the factory (or more precisely its {@link RepoTransport}s) is able to handle the given URL.
054         * @param remoteRoot the URL of the repository. Must not be <code>null</code>. This does not necessarily mean
055         * the repository is on a remote machine. It just means it is somewhere beyond this abstraction layer and might
056         * very well be on a remote server.
057         * @return <code>true</code>, if the URL is supported (i.e. a {@link RepoTransport} created by this factory will
058         * operate with it); <code>false</code>, if the URL is not supported.
059         */
060        boolean isSupported(URL remoteRoot);
061
062        /**
063         * Create a {@link RepoTransport} instance.
064         * @param remoteRoot the remote-root. Must not be <code>null</code>.
065         * @param clientRepositoryId the client-side repository's ID (i.e. the ID of the repo on the other side).
066         * May be <code>null</code>, if there is no repo (yet) on the other side. Note, that certain methods
067         * are not usable, if this is <code>null</code>.
068         * @return a new {@link RepoTransport} instance. Never <code>null</code>.
069         */
070        RepoTransport createRepoTransport(URL remoteRoot, UUID clientRepositoryId);
071
072}