org.neo4j.driver.v1.Driver Maven / Gradle / Ivy
Show all versions of neo4j-java-driver Show documentation
/*
* Copyright (c) 2002-2018 "Neo4j,"
* Neo4j Sweden AB [http://neo4j.com]
*
* This file is part of Neo4j.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.neo4j.driver.v1;
import java.util.concurrent.CompletionStage;
/**
* Accessor for a specific Neo4j graph database.
*
* Driver implementations are typically thread-safe, act as a template
* for {@link Session} creation and host a connection pool. All configuration
* and authentication settings are held immutably by the Driver. Should
* different settings be required, a new Driver instance should be created.
*
* A driver maintains a connection pool for each remote Neo4j server. Therefore
* the most efficient way to make use of a Driver is to use the same instance
* across the application.
*
* To construct a new Driver, use one of the
* {@link GraphDatabase#driver(String, AuthToken) GraphDatabase.driver} methods.
* The URI passed to
* this method determines the type of Driver created.
*
*
*
* URI Scheme Driver
* boltDirect driver: connects directly to the host and port specified in the URI.
*
*
* bolt+routingRouting driver: can automatically discover members of a Causal Cluster and route {@link Session sessions} based on {@link AccessMode}.
*
*
*
*
* @since 1.0 (bolt+routing URIs since 1.1)
*/
public interface Driver extends AutoCloseable
{
/**
* Return a flag to indicate whether or not encryption is used for this driver.
*
* @return true if the driver requires encryption, false otherwise
*/
boolean isEncrypted();
/**
* Create a new general purpose {@link Session}.
*
* Alias to {@code session(AccessMode.WRITE, null)}.
*
* @return a new {@link Session} object.
*/
Session session();
/**
* Create a new {@link Session} for a specific type of work.
*
* Alias to {@code session(mode, null)}.
*
* @param mode the type of access required by units of work in this session,
* e.g. {@link AccessMode#READ read access} or {@link AccessMode#WRITE write access}.
* @return a new {@link Session} object.
*/
Session session( AccessMode mode );
/**
* Create a new {@link AccessMode#WRITE write} {@link Session} with the specified initial bookmark.
* First transaction in the created session will ensure that server hosting is at least as up-to-date as the
* transaction referenced by the supplied bookmark.
*
* Alias to {@code session(AccessMode.WRITE, bookmark)}.
*
* @param bookmark the initial reference to some previous transaction. A {@code null} value is permitted, and
* indicates that the bookmark does not exist or is unknown.
* @return a new {@link Session} object.
*/
Session session( String bookmark );
/**
* Create a new {@link Session} for a specific type of work with the specified initial bookmark.
* First transaction in the created session will ensure that server hosting is at least as up-to-date as the
* transaction referenced by the supplied bookmark.
*
* @param mode the type of access required by units of work in this session,
* e.g. {@link AccessMode#READ read access} or {@link AccessMode#WRITE write access}.
* @param bookmark the initial reference to some previous transaction. A {@code null} value is permitted, and
* indicates that the bookmark does not exist or is unknown.
* @return a new {@link Session} object.
*/
Session session( AccessMode mode, String bookmark );
/**
* Create a new {@link AccessMode#WRITE write} {@link Session} with specified initial bookmarks.
* First transaction in the created session will ensure that server hosting is at least as up-to-date as the
* latest transaction referenced by the supplied iterable of bookmarks.
*
* Alias to {@code session(AccessMode.WRITE, bookmarks)}.
*
* @param bookmarks initial references to some previous transactions. Both {@code null} value and empty iterable
* are permitted, and indicate that the bookmarks do not exist or are unknown.
* @return a new {@link Session} object.
*/
Session session( Iterable bookmarks );
/**
* Create a new {@link AccessMode#WRITE write} {@link Session} with specified initial bookmarks.
* First transaction in the created session will ensure that server hosting is at least as up-to-date as the
* latest transaction referenced by the supplied iterable of bookmarks.
*
* Alias to {@code session(AccessMode.WRITE, bookmarks)}.
*
* @param mode the type of access required by units of work in this session,
* e.g. {@link AccessMode#READ read access} or {@link AccessMode#WRITE write access}.
* @param bookmarks initial references to some previous transactions. Both {@code null} value and empty iterable
* are permitted, and indicate that the bookmarks do not exist or are unknown.
* @return a new {@link Session} object.
*/
Session session( AccessMode mode, Iterable bookmarks );
/**
* Close all the resources assigned to this driver, including open connections and IO threads.
*
* This operation works the same way as {@link #closeAsync()} but blocks until all resources are closed.
*/
@Override
void close();
/**
* Close all the resources assigned to this driver, including open connections and IO threads.
*
* This operation is asynchronous and returns a {@link CompletionStage}. This stage is completed with
* {@code null} when all resources are closed. It is completed exceptionally if termination fails.
*
* @return a {@link CompletionStage completion stage} that represents the asynchronous close.
*/
CompletionStage closeAsync();
}