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.util.concurrent.TimeUnit;
025 import javax.transaction.xa.XAResource;
026 import net.jcip.annotations.NotThreadSafe;
027 import org.jboss.dna.graph.ExecutionContext;
028 import org.jboss.dna.graph.cache.CachePolicy;
029 import org.jboss.dna.graph.requests.Request;
030
031 /**
032 * A connection to a repository source.
033 * <p>
034 * These connections need not support concurrent operations by multiple threads.
035 * </p>
036 *
037 * @author Randall Hauch
038 */
039 @NotThreadSafe
040 public interface RepositoryConnection {
041
042 /**
043 * Get the name for this repository source. This value should be the same as that {@link RepositorySource#getName() returned}
044 * by the same {@link RepositorySource} that created this connection.
045 *
046 * @return the identifier; never null or empty
047 */
048 String getSourceName();
049
050 /**
051 * Return the transactional resource associated with this connection. The transaction manager will use this resource to manage
052 * the participation of this connection in a distributed transaction.
053 *
054 * @return the XA resource, or null if this connection is not aware of distributed transactions
055 */
056 XAResource getXAResource();
057
058 /**
059 * Ping the underlying system to determine if the connection is still valid and alive.
060 *
061 * @param time the length of time to wait before timing out
062 * @param unit the time unit to use; may not be null
063 * @return true if this connection is still valid and can still be used, or false otherwise
064 * @throws InterruptedException if the thread has been interrupted during the operation
065 */
066 boolean ping( long time,
067 TimeUnit unit ) throws InterruptedException;
068
069 /**
070 * Set the listener that is to receive notifications to changes to content within this source.
071 *
072 * @param listener the new listener, or null if no component is interested in the change notifications
073 */
074 void setListener( RepositorySourceListener listener );
075
076 /**
077 * Get the default cache policy for this repository. If none is provided, a global cache policy will be used.
078 *
079 * @return the default cache policy
080 */
081 CachePolicy getDefaultCachePolicy();
082
083 /**
084 * Execute the supplied commands against this repository source.
085 *
086 * @param context the environment in which the commands are being executed; never null
087 * @param request the request to be executed; never null
088 * @throws RepositorySourceException if there is a problem loading the node data
089 */
090 void execute( ExecutionContext context,
091 Request request ) throws RepositorySourceException;
092
093 /**
094 * Close this connection to signal that it is no longer needed and that any accumulated resources are to be released.
095 */
096 void close();
097 }