Graph Database Access - Wolfgang-Schuetzelhofer/jcypher GitHub Wiki

JCypher provides database access in a uniform way to remote as well as to embedded graph databases (including in-memory databases). If you access graph databases at a 'low' level of abstraction, you work against a slim Interface: IDBaccess. Most importantly, IDBAccess provides to execute Query-DSL-Expressions against a graph database. You create instances of IDBAccess by means of the factory class DBAccessFactory. When creating an IDBAccess instance, you specify how to access the database (REMOTE, EMBEDDED, IN_MEMORY), and you specify which database to access (the location of the database) by means of a set of properties. The root package for database access related classes (at this level of abstraction) is iot.jcypher.database.

// properties for remote access and for embedded access
// (additional properties for in memory and embedded access are optional)
Properties props = new Properties();

/** Note: You can put properties for different types of database access
    into one Properties table. The DBAccessFactory will take
    the properties it needs for creating a certain type of
    database access and ignore other ones */
		
// properties for remote access
props.setProperty(DBProperties.SERVER_ROOT_URI, "http://localhost:7474");
// you can alternatively access remote databases using the BOLT protocol
// since JCypher release 3.5.0
props.setProperty(DBProperties.SERVER_ROOT_URI, "bolt://localhost:7687");

// properties for embedded access
props.setProperty(DBProperties.DATABASE_DIR, "C:/NEO4J_DBS/01");

/*** additional properties for in memory and embedded db access ********/
/*** an excerpt from class DBProperties ********************************/
/** OPTIONAL  e.g. "512M" */
public static final String PAGECACHE_MEMORY = "pagecache_memory";
/** OPTIONAL  e.g. "60" */
public static final String STRING_BLOCK_SIZE = "string_block_size";
/** OPTIONAL  e.g. "300" */
public static final String ARRAY_BLOCK_SIZE = "array_block_size";
	
// create an IDBAccess instance	
IDBAccess remote =
   DBAccessFactory.createDBAccess(DBType.REMOTE, props);
IDBAccess embedded =
   DBAccessFactory.createDBAccess(DBType.EMBEDDED, props);
IDBAccess inMemory =
   DBAccessFactory.createDBAccess(DBType.IN_MEMORY, props);

// For an overview about available properties please
// have a look at the interface: DBProperties

Since JCypher release 2.6.0, basic authentication and authorization by means of userid and password are supported. If auth is enabled on a remote database, you have to invoke a different factory method to create an IDBAccess.

String userId = ...;
String passWord = ...;
IDBAccess remote =
   DBAccessFactory.createDBAccess(DBType.REMOTE, props, userId, passWord);

Since JCypher release 3.7.0, extended authentication according to Neo4J's Bolt Driver specification is supported. In order to use extended Athentication you must specify Bolt access to the remote database (see above).

AuthToken auth = AuthTokens...;
IDBAccess remote =
   DBAccessFactory.createDBAccess(DBType.REMOTE, props, auth);

For every IDBAccess which is instantiated, a shutdown hook is registered automatically. The shutdown hook disposes all DB resources when the VM exits (even if you "Ctrl-C" the running application). Since JCypher release 3.8.0, you can avoid shutdown hooks being registered automatically. This comes in handy, if you work in managed environments, where there are explicit start/stop lifecycle events. To avoid registering a shutdown hook, do the following:

// create an IDBAccess instance
IDBAccess remote =
   DBAccessFactory.createDBAccess(DBType.REMOTE, props).removeShutdownHook();

With JCypher release 3.8.0 public constructors for IDBAccess implementations are provided. This allows for more flexible configurations of specific IDBAccess implementations. Although you are highly encouraged to use DBAccessFactory, you are no longer forced to do so.

Since JCypher release 3.9.0 you can set the planner strategy either globally or individually on a per query basis.

// Globally
DBAccessFactory.seGlobaltPlannerStrategy(PlannerStrategy.COST);

//Individually (overrides the global setting)
query = new JcQuery(PlannerStrategy.RULE);

Currently the planner strategy's default setting is PlannerStrategy.RULE. If you set PlannerStrategy.DEFAULT, the decision about the planner strategy is delegated to the database engine.