001/*
002 * ModeShape (http://www.modeshape.org)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *       http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.modeshape.jdbc.delegate;
017
018import java.sql.Connection;
019import java.sql.SQLException;
020import java.sql.Statement;
021import java.util.Collection;
022import java.util.Set;
023import javax.jcr.RepositoryException;
024import javax.jcr.nodetype.NodeType;
025import javax.jcr.query.QueryResult;
026import org.modeshape.jdbc.DriverInfo;
027
028/**
029 * Represents the communication interface thru which the JDBC logic will obtain a connection and issue commands to the Jcr layer.
030 */
031
032public interface RepositoryDelegate {
033
034    /**
035     * Call to get the connection information.
036     * 
037     * @return ConnectionInfo
038     */
039    ConnectionInfo getConnectionInfo();
040
041    /**
042     * Called when the {@link Statement} the is closed. This enables the underlying connection to the JcrRepository remain open
043     * until the statement is finished using it.
044     */
045    void closeStatement();
046
047    /**
048     * Call to close the delegate connection and any outstanding transactions will be closed.
049     * 
050     * @see java.sql.Connection#close()
051     */
052    void close();
053
054    /**
055     * Call to get {@link NodeType} based on specified name
056     * 
057     * @param name
058     * @return NodeType
059     * @throws RepositoryException
060     */
061    NodeType nodeType( String name ) throws RepositoryException;
062
063    /**
064     * Call to get all the {@link NodeType}s defined.
065     * 
066     * @return List of all the node types.
067     * @throws RepositoryException
068     */
069    Collection<NodeType> nodeTypes() throws RepositoryException;
070
071    /**
072     * Call to execute the <code>query</code> based on the specified JCR language.
073     * 
074     * @param query is the query expression to execute
075     * @param language is the JCR language the <code>query</code> should be executed based on.
076     * @return QueryResult is the JCR query result
077     * @throws RepositoryException
078     */
079    QueryResult execute( String query,
080                         String language ) throws RepositoryException;
081
082    /**
083     * Generate the plan for the <code>query</code> based on the specified JCR language.
084     * 
085     * @param query is the query expression to execute
086     * @param language is the JCR language the <code>query</code> should be executed based on.
087     * @return the string representation of the query plan
088     * @throws RepositoryException
089     */
090    String explain( String query,
091                    String language ) throws RepositoryException;
092
093    /**
094     * Call to create the connection based on the implementation of this interface.
095     * 
096     * @param info the driver information
097     * @return Connection
098     * @throws SQLException
099     * @see java.sql.Driver#connect(String, java.util.Properties)
100     */
101    Connection createConnection( DriverInfo info ) throws SQLException;
102
103    /**
104     * @see java.sql.Connection#commit()
105     * @throws RepositoryException
106     */
107
108    void commit() throws RepositoryException;
109
110    /**
111     * @see java.sql.Connection#rollback()
112     * @throws RepositoryException
113     */
114    void rollback() throws RepositoryException;
115
116    /**
117     * @see java.sql.Connection#isValid(int)
118     * @param timeout
119     * @return boolean indicating if timeout is valid
120     * @throws RepositoryException
121     */
122    boolean isValid( int timeout ) throws RepositoryException;
123
124    /**
125     * @see java.sql.Wrapper#isWrapperFor(java.lang.Class)
126     * @param iface
127     * @return boolean
128     */
129    boolean isWrapperFor( Class<?> iface );
130
131    /**
132     * @see java.sql.Wrapper#unwrap(java.lang.Class)
133     * @param iface
134     * @param <T>
135     * @return <T> T
136     * @throws SQLException
137     */
138    <T> T unwrap( Class<T> iface ) throws SQLException;
139
140    /**
141     * Called to get all the repository names currently available in the ModeShapeEngine.
142     *
143     * @return Set<String> of repository names
144     * @throws RepositoryException
145     */
146    Set<String> getRepositoryNames() throws RepositoryException;
147
148    /**
149     * Returns the value for the requested <code>descriptorKey</code>
150     * 
151     * @param descriptorKey
152     * @return String descriptor value
153     */
154    String getDescriptor( String descriptorKey );
155
156}