Skip to content

Commit

Permalink
feat: Reorganize code
Browse files Browse the repository at this point in the history 
* Improve `Vertex`, `Edge`, and `Path` class
* Fix bugs in parsing routine for `graphpath` type
  * Merge the logic into `Path` and remove `TopCommaTokenizer`
* Change `GID` to `GraphId` and improve it
* Improve `Jsonb` and move it to `net.bitnine.agensgraph.util` package
* Introduce `AgConnection`, `AgStatement`, and `AgResultSet`
  * Remove surrounding '"' character from JSON string
  * Handle JSON values properly
* Improve named parameter feature
  * Introduce `AgPreparedStatement`
  * Merge features in `NamedParameterStatement` into `AgPreparedStatement`
  * Improve parsing routine for named parameters
* Rewrite the API to create JSON value
  * Introduce `JsonUtil`, `JsonbArrayBuilder`, and `JsonbObjectBuilder`
  * Remove `JsonArray` and `JsonObject`
* Remove unused classes
  * `AbstractDatabaseMetaData`
  * `AgensGraphConnection`
  * `AgensGraphDatabaseMetaData`
* Remove all existing tests and write unit tests
* Upgrade PostgreSQL JDBC Driver from 42.1.1.jre7 to 42.1.4.jre7
* Change version from 1.3.2 to 1.4.0
* Update README
  • Loading branch information
@protodef
protodef committed Oct 14, 2017
1 parent f8fdaef commit 5c57a4a
Show file tree
Hide file tree
Showing 43 changed files with 4,846 additions and 3,426 deletions.
118 changes: 67 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,37 @@
<img src="http://cfile26.uf.tistory.com/image/251E994857553C91236F07" />

# AgensGraph JDBC driver
# AgensGraph JDBC Driver

## Introduction ##

AgensGraph's JDBC driver is based on PostgreSQL JDBC Driver and offering Java Driver for Java application developer. Thus, When users develop some application, there is little difference between using the API of AgensGraph Java Driver and Postgres JDBC Driver. The only difference is that AgensGraph uses Cypher query language instead of SQL and utilizes Graph Data as data type like Vertex, Edge and Path.
AgensGraph JDBC Driver is based on PostgreSQL JDBC Driver and offers additional features to handle graph data. Thus, when users develop Java applications, there is little difference between using the API of AgensGraph JDBC Driver and PostgreSQL JDBC Driver. The only difference is that AgensGraph uses Cypher query language instead of SQL and utilizes graph data as data types such as `Vertex`, `Edge` and `Path`.

## Usage of Java Driver ##

This section will handle how to use Java Driver through examples.
This section shows how to use AgensGraph JDBC Driver through examples.

### Get the Driver ###

You can download the precompiled driver(jar) from [bitnine.net/downloads](http://bitnine.net/downloads) or use maven as follows
You can download the precompiled driver(jar) from [bitnine.net/downloads](http://bitnine.net/downloads) or use maven as follows.
```xml
<dependency>
<groupId>net.bitnine</groupId>
<artifactId>agensgraph-jdbc</artifactId>
<version>1.2.0</version>
<version>1.4.0</version>
</dependency>
```
You can search the latest version on [The Central Repository with GroupId and ArtifactId](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22net.bitnine%22%20AND%20a%3A%22agensgraph-jdbc%22)
You may search the latest version on [The Central Repository with GroupId and ArtifactId](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22net.bitnine%22%20AND%20a%3A%22agensgraph-jdbc%22)

### Connection ###

It requires two information to connect AgensGraph using Java Driver like as the way that other JDBC Drivers do. These are the name of class to be loading Java Driver and the connection string.
It requires two strings to connect AgensGraph using the driver like other JDBC drivers do. These are the name of the driver class and a connection string.

* The name of class is `net.bitnine.agensgraph.Driver`.
* connection string consists of sub-protocol, server, port, database.
* `jdbc:agensgraph://`is a sub-protocal to use particular Driver and a hold value.
* It is written in format of `jdbc:agensgraph://server:port/database` including sub-protocol.
* The name of the driver class is `net.bitnine.agensgraph.Driver`.
* A connection string consists of sub-protocol, server, port, and database.
* `jdbc:agensgraph://` is a sub-protocal to use AgensGraph JDBC driver.
* The format of a connection string is `jdbc:agensgraph://server:port/database`.

The following is an example code to connect AgensGraph. It is connected to the AgensGraph through Connection object and ready to perform the query.
The following is an example to connect AgensGraph.

```java
import java.sql.DriverManager;
Expand All @@ -51,73 +51,89 @@ public class AgensGraphTest {

### Retrieving Data ###

This is an example to export Graph data using MATCH.

A Cypher query is executed using `executeQuery()`. The output is ResultSet object, which is the same output format in JDBC.
The output of query is the ‘vertex’ type of AgensGraph. Java Driver returns this output as Vertex instance. Because Vertex class is a sub-class of JsonObject, users can obtain information from the property fields.
The following is an example of retrieving graph data using `MATCH` clause. The result of the query is `vertex` type in AgensGraph. You can get the result as a `Vertex` object and get properties in it.

```java
import java.sql.DriverManager;
import java.sql.Connection;
import java.sql.Statement;
import java.sql.ResultSet;

...
import net.bitnine.agensgraph.graph.Vertex;

...
public class AgensGraphTest {
public static void main(String[] args) {
...
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(
"MATCH (:Person {name: 'John'})-[:knows]-(friend:Person)" +
"RETURN friend");
"MATCH (:person {name: 'John'})-[:knows]-(friend:person) RETURN friend");
while (rs.next()) {
Vertex friend = (Vertex)rs.getObject(1);
System.out.println(friend.getProperty().getString("name"));
System.out.println(friend.getProperty().getInt("age"));
Vertex friend = (Vertex) rs.getObject(1);
System.out.println(friend.getString("name"));
System.out.println(friend.getInt("age"));
}
}
}
```

### Create Data ###
### Creating Data ###

The following is an example, which is inputting a vertex with Person label to AgensGraph.
Users can input a property of a vertex using strings in Cypher queries. They are also able to be binded after making JsonObject like a following example
The following example shows how to create a vertex with `person` label. You can build a `Jsonb` object to use it as the property map of the created vertex.

```java
import java.sql.DriverManager;
import java.sql.Connection;
import java.sql.PreparedStatement;

import net.bitnine.agensgraph.graph.property.JsonObject;
...
import net.bitnine.agensgraph.util.Jsonb;
import net.bitnine.agensgraph.util.JsonbUtil;

import java.sql.PreparedStatement;
...
public class AgensGraphTest {
public static void main(String[] args) {
...
PreparedStatement pstmt = con.prepareStatement("CREATE (:Person ?)");
JsonObject john = new JsonObject();
john.put("name", "John");
john.put("from", "USA");
john.put("age", 17);
pstmt.setObject(1, john);
PreparedStatement pstmt = conn.prepareStatement("CREATE (:person ?)");
Jsonb j = JsonbUtil.createObjectBuilder()
.add("name", "John")
.add("from", "USA")
.add("age", 17)
.build();
pstmt.setObject(1, j);
pstmt.execute();
}
}
```

The following is converted format to using string.
The following is the actual query to be executed.

`CREATE (:Person {name: 'John', from: 'USA', age: 17})`
`CREATE (:person {name: 'John', from: 'USA', age: 17})`

### Using Named Parameter ###

```java
...
import net.bitnine.agensgraph.jdbc.AgConnection;
import net.bitnine.agensgraph.jdbc.AgPreparedStatement;
...
public class AgensGraphTest {
public static void main(String[] args) {
...
aconn = conn.unwrap(AgConnection.class);
AgPreparedStatement apstmt = aconn.prepareNamedParameterStatement("CREATE ($data)");
Jsonb j = JsonbUtil.createObjectBuilder()
.add("id", 7)
.add("enabled", true)
.add("day", JsonbUtil.createArray("Sat", "Sun"))
.build();
apstmt.setObject("data", j);
apstmt.execute();
}
}
```

## Graph Classes ##
## Graph Object Classes ##

This section is a brief explanation of Java class to support graph data.

| Class | Description |
| ---------- | ----------- |
| Vertex | It is a java class corresponding to a `vertex` type in the AgensGraph. It supports accessing methods for the label and properties. |
| Edge | It is a java class corresponding to a `edge` type in the AgensGraph. It supports accessing methods for the label and properties. |
| Path | It is a java class corresponding to a `graphpath` type in the AgensGraph. It supports methods for the length of the path, and accessing for vertexes and edges in the path. |
| JsonObject | It is a java class corresponding to the property field of Vertex and Edge class. Property field is JSON class. It offers accessing methods for property values by name. As the above CREATE example, it offers methods to create or modify JSON object. |
| JsonArray | It is a java class in corresponding with JSON array. It offers accessing methods for the element of JSON array using index. It also offers various methods to create or modify of JSON array.|
| Class | Description |
| ------------ | ----------- |
| `GraphId` | It is a java class corresponding to `graphid` type in AgensGraph. |
| `Vertex` | It is a java class corresponding to `vertex` type in AgensGraph. It supports accessing methods for the label and properties. |
| `Edge` | It is a java class corresponding to `edge` type in AgensGraph. It supports accessing methods for the label and properties. |
| `Path` | It is a java class corresponding to `graphpath` type in AgensGraph. It supports methods for the length of the path, and accessing for vertexes and edges in the path. |
| `Jsonb` | It is a java class corresponding to `jsonb` type in AgensGraph. `Vertex` and `Edge` use `Jsonb` to store their properties. It offers accessing methods for JSON scalar, array, and object type. |
| `JsonbUtil` | It offers various methods to create `Jsonb` object as shown in the above `CREATE` example. |
4 changes: 2 additions & 2 deletions pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

<groupId>net.bitnine</groupId>
<artifactId>agensgraph-jdbc</artifactId>
<version>1.3.2</version>
<version>1.4.0</version>
<packaging>jar</packaging>

<name>Agensgraph JDBC</name>
Expand Down Expand Up @@ -61,7 +61,7 @@
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>42.1.1.jre7</version>
<version>42.1.4.jre7</version>
</dependency>
<dependency>
<groupId>com.googlecode.json-simple</groupId>
Expand Down
Loading

0 comments on commit 5c57a4a

Please sign in to comment.