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 }