001    /*
002     * JBoss, Home of Professional Open Source.
003     * Copyright 2008, Red Hat Middleware LLC, and individual contributors
004     * as indicated by the @author tags. See the copyright.txt file in the
005     * distribution for a full listing of individual contributors. 
006     *
007     * This is free software; you can redistribute it and/or modify it
008     * under the terms of the GNU Lesser General Public License as
009     * published by the Free Software Foundation; either version 2.1 of
010     * the License, or (at your option) any later version.
011     *
012     * This software is distributed in the hope that it will be useful,
013     * but WITHOUT ANY WARRANTY; without even the implied warranty of
014     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015     * Lesser General Public License for more details.
016     *
017     * You should have received a copy of the GNU Lesser General Public
018     * License along with this software; if not, write to the Free
019     * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020     * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021     */
022    package org.jboss.dna.graph.connectors;
023    
024    import java.io.Serializable;
025    import javax.naming.Referenceable;
026    
027    /**
028     * A repository source is a description of a resource that can be used to access or store repository information. This class
029     * serves as a factory for {@link RepositoryConnection} instances and provides some basic configuration information.
030     * <p>
031     * Typically this interface is implemented by classes that provide standard-style getters and setters for the various properties
032     * necessary for proper configuration via reflection or introspection. This interface expects nor defines any such properties,
033     * leaving that entirely to the implementation classes.
034     * </p>
035     * <p>
036     * Implementations should also provide a no-arg constructor so that it is possible to easily create instances and initialize using
037     * the standard getters and setters. One example where this is required is when a RepositorySource instance is recorded in a
038     * repository (e.g., in a configuration area), and needs to be reinstantiated.
039     * </p>
040     * <p>
041     * Objects that implement this <code>RepositorySource</code> interface are typically registered with a naming service such as Java
042     * Naming and Directory Interface<sup><font size=-3>TM</font></sup> (JNDI). This interface extends both {@link Referenceable} and
043     * {@link Serializable} so that such objects can be stored in any JNDI naming context and enable proper system recovery,
044     * </p>
045     * <p>
046     * If the connections to a source are to be pooled, see {@link RepositoryConnectionPool}.
047     * </p>
048     * 
049     * @author Randall Hauch
050     */
051    public interface RepositorySource extends Referenceable, Serializable {
052    
053        /**
054         * Initialize this source to use the supplied {@link RepositoryContext}, from which this source can obtain
055         * {@link RepositoryContext#getRepositoryConnectionFactory() connections} to other {@link RepositorySource sources} as well as
056         * {@link RepositoryContext#getExecutionContextFactory() execution contexts}.
057         * 
058         * @param context
059         * @throws RepositorySourceException
060         */
061        void initialize( RepositoryContext context ) throws RepositorySourceException;
062    
063        /**
064         * Get the name for this repository source.
065         * 
066         * @return the name; never null or empty
067         */
068        String getName();
069    
070        /**
071         * Get a connection from this source.
072         * 
073         * @return a connection
074         * @throws RepositorySourceException if there is a problem obtaining a connection
075         * @throws IllegalStateException if the factory is not in a state to create or return connections
076         */
077        RepositoryConnection getConnection() throws RepositorySourceException;
078    
079        /**
080         * Get the maximum number of retries that may be performed on a given operation when using {@link #getConnection()
081         * connections} created by this source. This value does not constitute a minimum number of retries; in fact, the connection
082         * user is not required to retry any operations.
083         * 
084         * @return the maximum number of allowable retries, or 0 if the source has no limit
085         */
086        int getRetryLimit();
087    
088        /**
089         * Set the maximum number of retries that may be performed on a given operation when using {@link #getConnection()
090         * connections} created by this source. This value does not constitute a minimum number of retries; in fact, the connection
091         * user is not required to retry any operations.
092         * 
093         * @param limit the maximum number of allowable retries, or 0 if the source has no limit
094         */
095        void setRetryLimit( int limit );
096    
097        /**
098         * Get the capabilities for this source.
099         * 
100         * @return the capabilities for this source; never null
101         */
102        RepositorySourceCapabilities getCapabilities();
103    
104    }