001 /*
002 * JBoss DNA (http://www.jboss.org/dna)
003 * See the COPYRIGHT.txt file distributed with this work for information
004 * regarding copyright ownership. Some portions may be licensed
005 * to Red Hat, Inc. under one or more contributor license agreements.
006 * See the AUTHORS.txt file in the distribution for a full listing of
007 * individual contributors.
008 *
009 * JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
010 * is licensed to you under the terms of the GNU Lesser General Public License as
011 * published by the Free Software Foundation; either version 2.1 of
012 * the License, or (at your option) any later version.
013 *
014 * JBoss DNA is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017 * Lesser General Public License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this software; if not, write to the Free
021 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
022 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
023 */
024 package org.jboss.dna.graph.connector;
025
026 import java.util.concurrent.TimeUnit;
027 import javax.transaction.xa.XAResource;
028 import net.jcip.annotations.NotThreadSafe;
029 import org.jboss.dna.graph.ExecutionContext;
030 import org.jboss.dna.graph.cache.CachePolicy;
031 import org.jboss.dna.graph.property.PathNotFoundException;
032 import org.jboss.dna.graph.property.ReferentialIntegrityException;
033 import org.jboss.dna.graph.request.CompositeRequest;
034 import org.jboss.dna.graph.request.Request;
035 import org.jboss.dna.graph.request.processor.RequestProcessor;
036
037 /**
038 * A connection to a repository source.
039 * <p>
040 * These connections need not support concurrent operations by multiple threads.
041 * </p>
042 * <h3>Implementing a connector</h3>
043 * <p>
044 * While most of these methods are straightforward, a few warrant additional information. The {@link #ping(long, TimeUnit)} method
045 * allows DNA to check the connection to see if it is alive. This method can be used in a variety of situations, ranging from
046 * verifying that a {@link RepositorySource}'s JavaBean properties are correct to ensuring that a connection is still alive before
047 * returning the connection from a connection pool.
048 * </p>
049 * <p>
050 * The most important method on this interface, though, is the {@link #execute(ExecutionContext, Request)} method, which serves as
051 * the mechanism by which the component using the connector access and manipulates the content exposed by the connector. The first
052 * parameter to this method is the {@link ExecutionContext}, which contains the information about environment as well as the
053 * subject performing the request.
054 * </p>
055 * <p>
056 * The second parameter, however, represents a request that is to be processed by the connector. {@link Request} objects can take
057 * many different forms, as there are different classes for each kind of request (see the {org.jboss.dna.graph.request} package
058 * for more detail). Each request contains the information a connector needs to do the processing, and it also is the place where
059 * the connector places the results (or the error, if one occurs).
060 * </p>
061 * <p>
062 * Although there are over a dozen different kinds of requests, we do anticipate adding more in future releases. For example, DNA
063 * will likely support searching repository content in sources through an additional subclass of {@link Request}. Getting the
064 * version history for a node will likely be another kind of request added in an upcoming release.
065 * </p>
066 * <p>
067 * A connector is technically free to implement the {@link #execute(ExecutionContext, Request)} method in any way, as long as the
068 * semantics are maintained. But DNA provides a {@link RequestProcessor} class that can simplify writing your own connector and at
069 * the same time help insulate your connector from new kinds of requests that may be added in the future. The
070 * {@link RequestProcessor} is an abstract class that defines a <code>process(...)</code> method for each concrete {@link Request}
071 * subclass. In other words, there is a {@link RequestProcessor#process(org.jboss.dna.graph.request.CompositeRequest)} method, a
072 * {@link RequestProcessor#process(org.jboss.dna.graph.request.ReadNodeRequest)} method, and so on.
073 * </p>
074 * <p>
075 * To use a request processor in your connector, simply subclass {@link RequestProcessor} and override all of the abstract methods
076 * and optionally override any of the other methods that have a default implementation. In many cases, the default implementations
077 * of the <code>process(...)</code> methods are <i>sufficient</i> but probably not <i>efficient or optimum.</i> If that is the
078 * case, simply provide your own methods that perform the request in a manner that is efficient for your source. However, if
079 * performance is not a big issue, all of the concrete methods will provide the correct behavior. And remember, you can always
080 * provide better implementations later, so it's often best to keep things simple at first.
081 * </p>
082 * <p>
083 * Then, in your connector's {@link #execute(ExecutionContext, Request)} method, instantiate your {@link RequestProcessor}
084 * subclass and pass the {@link #execute(ExecutionContext, Request) execute(...)} method's Request parameter directly into the the
085 * request processor's {@link RequestProcessor#process(Request)} method, which will determine the appropriate method given the
086 * actual Request object and will then invoke that method. For example:
087 *
088 * <pre>
089 * public void execute( ExecutionContext context,
090 * Request request ) throws RepositorySourceException {
091 * RequestProcessor processor = new RequestProcessor(context);
092 * try {
093 * proc.process(request);
094 * } finally {
095 * proc.close();
096 * }
097 * }
098 * </pre>
099 *
100 * If you do this, the bulk of your connector implementation will be in the RequestProcessor implementation methods. This not only
101 * is more maintainable, it also lends itself to easier testing. And should any new request types be added in the future, your
102 * connector may work just fine without any changes. In fact, if the {@link RequestProcessor} class can implement meaningful
103 * methods for those new request types, your connector may "just work". Or, at least your connector will still be binary
104 * compatible, even if your connector won't support any of the new features.
105 * </p>
106 * <p>
107 * Finally, how should the connector handle exceptions? As mentioned above, each {@link Request} object has a
108 * {@link Request#setError(Throwable) slot} where the connector can set any exception encountered during processing. This not only
109 * handles the exception, but in the case of a {@link CompositeRequest} it also correctly associates the problem with the request.
110 * However, it is perfectly acceptable to throw an exception if the connection becomes invalid (e.g., there is a communication
111 * failure) or if a fatal error would prevent subsequent requests from being processed.
112 * </p>
113 *
114 * @author Randall Hauch
115 */
116 @NotThreadSafe
117 public interface RepositoryConnection {
118
119 /**
120 * Get the name for this repository source. This value should be the same as that {@link RepositorySource#getName() returned}
121 * by the same {@link RepositorySource} that created this connection.
122 *
123 * @return the identifier; never null or empty
124 */
125 String getSourceName();
126
127 /**
128 * Return the transactional resource associated with this connection. The transaction manager will use this resource to manage
129 * the participation of this connection in a distributed transaction.
130 *
131 * @return the XA resource, or null if this connection is not aware of distributed transactions
132 */
133 XAResource getXAResource();
134
135 /**
136 * Ping the underlying system to determine if the connection is still valid and alive.
137 *
138 * @param time the length of time to wait before timing out
139 * @param unit the time unit to use; may not be null
140 * @return true if this connection is still valid and can still be used, or false otherwise
141 * @throws InterruptedException if the thread has been interrupted during the operation
142 */
143 boolean ping( long time,
144 TimeUnit unit ) throws InterruptedException;
145
146 /**
147 * Get the default cache policy for this repository. If none is provided, a global cache policy will be used.
148 *
149 * @return the default cache policy
150 */
151 CachePolicy getDefaultCachePolicy();
152
153 /**
154 * Execute the supplied commands against this repository source.
155 *
156 * @param context the environment in which the commands are being executed; never null
157 * @param request the request to be executed; never null
158 * @throws PathNotFoundException if the request(s) contain paths to nodes that do not exist
159 * @throws ReferentialIntegrityException if the request is or contains a delete operation, where the delete could not be
160 * performed because some references to deleted nodes would have remained after the delete operation completed
161 * @throws RepositorySourceException if there is a problem loading the node data
162 */
163 void execute( ExecutionContext context,
164 Request request ) throws RepositorySourceException;
165
166 /**
167 * Close this connection to signal that it is no longer needed and that any accumulated resources are to be released.
168 */
169 void close();
170 }