14.3.1.1 Oracle Graph Java Client

You can install the Java client from the oracle-graph-client-24.1.0.zip file that is shipped with Oracle Graph Server and Client or you can use the Java client on Maven Central.

14.3.1.1.1 Installing the Java Client From the Graph Server and Client Downloads

You can download the zip file for Oracle Graph Client 24.1.0 and install the Java client.

The prerequisites for installing the Java client are:
  • Supported Operating Systems: A Unix-based operation system (such as Linux), macOS, or Microsoft Windows
  • Supported JDK versions:
    • Oracle JDK 11 or JDK 17
    • OpenJDK JDK 11 or JDK 17

Note:

Due to a bug in Oracle JDK and OpenJDK, which causes a deadlock when you attempt to copy and paste into a JShell session, it is recommended that you avoid the following JDK versions:
  • JDK 11.0.9
  • JDK 11.0.10
  • JDK 11.0.11
  • JDK 11.0.12
  1. Download the Oracle Graph Client from Oracle Software Cloud.
    For example, oracle-graph-client-24.1.0.zip.
  2. Unzip the file into a directory of your choice.
  3. Configure your client to trust the self-signed keystore. See Configuring a Client to Trust the Self-Signed Keystore for more information.
  4. Start the OPG4J shell to connect to the graph server (PGX) as shown:
    cd <CLIENT_INSTALL_DIR>
    ./bin/opg4j --base_url https://<host>:7007 --username <graphuser>
    

    In the preceding code:

    • <CLIENT_INSTALL_DIR>: Directory where the shell executables are located.

      The shell executables are generally found in /opt/oracle/graph/bin after server installation, and <CLIENT_INSTALL_DIR>/bin after the client installation.

    • <host>: Server host

      Note:

      The graph server (PGX), listens on port 7007 by default. If needed, you can configure the graph server to listen on a different port by changing the port value in the server configuration file (server.conf). See Configuring the Graph Server (PGX) for details.
    • <graphuser>: Database user

    You will be prompted for the database password.

    See Starting the OPG4J Shell for more information on the different ways you can start the OPG4J shell.

    The OPG4J shell starts and the following command line prompt appears as shown:

    For an introduction type: /help intro
    Oracle Graph Server Shell 24.1.0
    Variables instance, session, and analyst ready to use.
    opg4j>

    See Also:

    Java API Reference for more information on the Java APIs

14.3.1.1.2 Using Oracle Graph Java Client on Maven Central

You can obtain the property graph Java client from Maven Central.

The Maven artifact for the graph Java client is described as follows:
  • Group Name: com.oracle.database.graph
  • Artifact Name: opg-client
  • Version: 24.1.0

You can perform the following steps to use the graph Java client from Maven Central:

  1. Download and Install Apache Maven on your system.
    See Apache Maven Project for more information.
  2. Add the bin folder with the mvn command to the PATH variable.
  3. Build your Maven project and navigate to the project directory.
  4. Edit the pom.xml file on the following:
    1. Add the graph Java client dependency as shown:
      <dependencies>
          <dependency>
            <groupId>com.oracle.database.graph</groupId>
            <artifactId>opg-client</artifactId>
            <version>24.1.0</version>
          </dependency>
      </dependencies>

      Note:

      If you use Gradle as a build tool, then the equivalent dependency declaration for the Java client is:

      implementation group: 'com.oracle.database.graph', name: 'opg-client', version: '24.1.0'

    2. Add the following repository as the Java client depends on the Spoofax Language Workbench Library to compile PGQL queries:
      <repositories>
          <repository>
            <id>spoofax</id>
            <url>https://artifacts.metaborg.org/content/repositories/releases</url>
          </repository>
      </repositories>
  5. Optionally, you can skip step 4 and copy the following minimal POM configuration in <project_dir>/pom.xml file:
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
      <modelVersion>4.0.0</modelVersion>
      <groupId>com.mycompany.app</groupId>
      <artifactId>my-app</artifactId>
      <packaging>jar</packaging>
      <version>1.0-SNAPSHOT</version>
      <name>my-app</name>
      <repositories>
        <repository>
          <id>spoofax</id>
          <url>https://artifacts.metaborg.org/content/repositories/releases</url>
        </repository>       
      </repositories>
      <dependencies>
        <dependency>
          <groupId>com.oracle.database.graph</groupId>
          <artifactId>opg-client</artifactId>
          <version>24.1.0</version>
        </dependency>
      </dependencies>
    </project>
  6. Build your Java code in <project_dir>/src/main/java/com/mycompany/app and compile with Maven.
    For example, the following code is stored in a file <project_dir>/src/main/java/com/mycompany/app/App1.java:
    package com.mycompany.app;
     
    import java.sql.DriverManager;
    import java.sql.Connection;
    import java.sql.Statement;
    import oracle.pg.rdbms.pgql.PgqlConnection;
    import oracle.pg.rdbms.pgql.PgqlStatement;
    import oracle.pg.rdbms.pgql.PgqlResultSet;
    import oracle.pgx.api.*;
    import oracle.pg.rdbms.GraphServer;
    import oracle.pg.rdbms.pgql.jdbc.PgqlJdbcRdbmsDriver;
    
    public class App1 {
     
      public static void main(String[] args) throws Exception {
        String dbConnectString = args[0];
        String username = args[1];
        String password = args[2];
     
        // Obtain a JDBC database connection
        DriverManager.registerDriver(new PgqlJdbcRdbmsDriver());
        String jdbcUrl = "jdbc:oracle:pgql:@" + dbConnectString;
        System.out.println("connecting to " + jdbcUrl);
    
        try (Connection conn = DriverManager.getConnection(jdbcUrl, username, password)) {
          conn.setAutoCommit(false);
    
          // Create PGQL connection
          PgqlConnection pgqlConn = PgqlConnection.getConnection(conn);
    
          // Create a PGQL statement to execute PGQL queries
          PgqlStatement pgqlStmt = pgqlConn.createStatement();
    
          // Create a PGQL property graph using the CREATE PROPERTY GRAPH statement
          String pgPgqlName = "BANK_GRAPH";
          String createPgPgqlQuery = 
              "CREATE PROPERTY GRAPH " + pgPgqlName + " " +
              "VERTEX TABLES ( BANK_ACCOUNTS AS ACCOUNTS " +
              "KEY (ID) " +
              "LABEL ACCOUNTS " +
              "PROPERTIES (ID, NAME)" +
              ") " +
              "EDGE TABLES ( BANK_TXNS AS TRANSFERS " +
              "KEY (FROM_ACCT_ID, TO_ACCT_ID, AMOUNT) " +
              "SOURCE KEY (FROM_ACCT_ID) REFERENCES ACCOUNTS (ID) " +
              "DESTINATION KEY (TO_ACCT_ID) REFERENCES ACCOUNTS (ID) " +
              "LABEL TRANSFERS " +
              "PROPERTIES (FROM_ACCT_ID, TO_ACCT_ID, AMOUNT, DESCRIPTION)" +
              ") OPTIONS(PG_PGQL)";
    
          pgqlStmt.execute(createPgPgqlQuery);
    
          // Execute a query to retrieve the first 10 elements of the graph
          String pgqlQuery = 
              "SELECT e.from_acct_id, e.to_acct_id, e.amount FROM " +
              "MATCH (n:ACCOUNTS) -[e:TRANSFERS]-> (m:ACCOUNTS) ON " +
              pgPgqlName + " LIMIT 10";
    
          PgqlResultSet rs = pgqlStmt.executeQuery(pgqlQuery);
          rs.print();
    
          // Drop the PGQL property graph using the DROP PROPERTY GRAPH statement
          String dropPgPgqlQuery = "DROP PROPERTY GRAPH " + pgPgqlName;
          pgqlStmt.execute(dropPgPgqlQuery);
        }
        System.exit(0);
      }
    }

    You can then compile and run the preceding code by navigating to your project directory and running the following command:

    mvn compile exec:java -Dexec.mainClass="com.mycompany.app.App1"-Dexec.arguments='<db-connect-string>,<username>,<password>'

    On successful processing, the code may produce an output similar to the following. Note, your output may be different depending on your <db-connect-string>.

    [INFO] --- exec-maven-plugin:3.1.0:java (default-cli) @ my-app ---
    connecting to jdbc:oracle:pgql:@myhost:1521/oradb
    name = Baz