Java QuickStart

15 minutes

The InterSystems JDBC driver supports three lightweight Java APIs that provide direct access to InterSystems IRIS® databases via relational tables, objects, or multidimensional storage.

Java features available in InterSystems IRIS include:

  • Relational access through the JDBC API
  • Object access through the InterSystems XEP API
  • Access to multidimensional storage through the InterSystems Native API
  • Multi-model access to use multiple APIs together
  • Support for third-party APIs such as Hibernate
  • An underlying consistent structure, avoiding data duplication

Watch the video or try the exercise below.

With Java, you can interact with InterSystems IRIS relationally (with JDBC), using objects (with XEP), or natively (with the Native API). In the steps below, you will access a set of sample stock data using each of the ways described.

Set up


  1. First, make sure you have an instance of InterSystems IRIS and a multi-language IDE ready to go.

    If you don’t have InterSystems IRIS yet, get a free, online development sandbox here. Log in with your InterSystems universal account, or register for one below.

  2. Clone the quickstarts-java repo into the /home/project directory in the cloud IDE whose settings are above. Open the IDE . Then in the IDE’s terminal window:
    cd /home/project
    git clone -b try-iris https://github.com/intersystems/quickstarts-java
    
  3. Using the Explorer pane (the file browser encompassing the left side of the IDE), open the quickstarts-java folder, and then the src folder. Then open the config.txt file and change the value of IP to (provision a sandbox to get this setting) and the value of port to (provision a sandbox to get this setting).

SQL-based access with JDBC

Use the standard JDBC API for SQL-based access to relational tables.

  1. In the same src folder, open jdbcplaystocksTask7.java to view the JDBC code. You will notice the connection string uses these variables to connect:
    String dbUrl = protocol + ip + ":" + port + "/" + namespace;
  2. Build and run jdbcplaystocksTask7.java:
    cd /home/project/quickstarts-java/src
    javac -cp ".:../lib/intersystems-jdbc-3.0.0.jar" jdbcplaystocksTask7.java
    java -cp ".:../lib/intersystems-jdbc-3.0.0.jar" jdbcplaystocksTask7
  3. This code simulates a stock trading application, allowing you to manage your personal portfolio and see how you would have done selling on a particular date.
    • Run option 1: View the top 10 stocks on 2016-08-12.
    • Run option 2: Create the Portfolio table.
    • Run option 3: Add three new portfolio items (for AMZN, GOOGL, and EQIX) using a value between the opening and closing price on 2016-08-12.
    • Run option 6: Then, see how much you would have made on your portfolio if selling on 2017-08-10.
    • Run option 7: Quit.

XEP for high-performance inserts

Use XEP for high-performance, real-time object insertions.

  1. Open xepplaystocksTask6.java to view the XEP code. You will notice the connection string uses these variables to connect:
    xepPersister.connect(ip, port, namespace, username, password);
  2. Compile and run xepplaystocksTask6.java:
    cd /home/project/quickstarts-java/src
    javac -cp ".:../lib/intersystems-jdbc-3.0.0.jar:../lib/intersystems-xep-3.0.0.jar" xepplaystocksTask6.java
    java -cp ".:../lib/intersystems-jdbc-3.0.0.jar:../lib/intersystems-xep-3.0.0.jar" xepplaystocksTask6
  3. This code simulates real-time stock trades.
    • Run option 1: Make a sample trade. For example, trade two shares on 2016-08-12 for $300/share, using your own name as the stock name and trader.
    • Run option 2: Save this trade.
    • Run option 3: Generate 500 generic trades.
    • Run option 5: Retrieve the trade objects from the database.
    • Run option 6: Retrieve the trade objects from the database again and update the names to prepend NYSE-to each stock name
    • Run option 7: Quit.

With XEP, you can efficiently stores objects directly to InterSystems IRIS, requiring no translation to rows.

Native API to store and exercise a custom structure

Use the Native API to store to a custom structure and call methods or routines.

  1. Open nativeplaystocksTask5.java to view the Native API code. You will notice the connection string uses these variables to connect: String dbUrl = protocol + ip + ":" + port + "/" + namespace;. Notice this code uses the standard JDBC connection.
  2. Run nativeplaystocksTask5.java:
    cd /home/project/quickstarts-java/src
    javac -cp ".:../lib/intersystems-jdbc-3.0.0.jar" nativeplaystocksTask5.java
    java -cp ".:../lib/intersystems-jdbc-3.0.0.jar" nativeplaystocksTask5
  3. This code stores stock data in a custom data structure.
    • Run option 1: Write to a test global.
    • Run option 2: Store the stock data in a custom structure.
    • Run option 3: Retrieve and view the stock data from this custom structure.
    • Run option 4: Call population methods within InterSystems IRIS to generate better information for trades (as seen in the XEP example above).
    • Run option 5: Print the version of InterSystems IRIS by directly calling a routine within InterSystems IRIS.
    • Run option 6: Quit.

With the Native API, you can efficiently store data in your own custom data structure, allowing you to answer questions you could not answer using tables or objects. Additionally, you can call class methods and routines from within InterSystems IRIS using the Native API.

Use JDBC, XEP, and Native access side by side

Use JDBC, XEP, and Native access side by side, choosing the best model for each task.

  1. Look at multimodelplaystocksTask4.java to see how all APIs work together. You will notice the connection string uses these variables to connect:
    xepPersister.connect(ip, port, namespace, username, password);
    Notice this code connects using the XEP connection. Since EventPersister inherits from IRISConnection, all ways to connect leverage the same underlying connection to InterSystems IRIS.
  2. Compile and run multimodelplaystocksTask4.java:
    cd /home/project/quickstarts-java/src
    javac -cp ".:../lib/intersystems-jdbc-3.0.0.jar:../lib/intersystems-xep-3.0.0.jar" multimodelplaystocksTask4.java
    java -cp ".:../lib/intersystems-jdbc-3.0.0.jar:../lib/intersystems-xep-3.0.0.jar" multimodelplaystocksTask4
  3. This code stores stock company information.
    • JDBC is used to quickly retrieve all distinct stock names from the Demo.Stock table.
    • Native API is used to call population methods within InterSystems IRIS for founder and mission statement.
    • XEP is used to store these objects directly to the database, avoiding any translation back to tables.

With InterSystems IRIS, you can use one connection and use the method that is best for each task, decreasing the time it takes to develop your applications while also increasing your application performance. XEP efficiently stores objects directly to InterSystems IRIS, requiring no translation to rows. It is worth mentioning that JDBC can also be used now to retrieve the data stored using XEP, reducing data redundancy.