The Java connector gives an easy entry-point to use OKAPI software from within your own code. You can access its source code via Github. Just make sure that you are using the right connector with the right version of OKAPI running on the server.
This guide gives you an overview of:
- How to get and compile the code
- A short explanation of how the connector works
Getting and compiling the code
In this short description, we will set-up the code using Eclipse. You can, of course, use any other IDE and/or build-system of your choice. To follow the single steps, you will need the following dependencies:
- Java SDK (we used 12.0.1, but older ones should work),
- Java Runtime Environment,
- Eclipse for Java Developers (we used 2019-03 and 2019-06),
- java-json.jar (you can get for example from here: https://www.java2s.com/Code/Jar/j/Downloadjavajsonjar.htm)
The rest should be available with your Java installation.
Now, to compile the code, first open eclipse. In there, start a new java project. Instead of giving the project a name, uncheck the “Use default location” and choose the cloned repository as location. Click on “Finish”, and you have your project created.
Before being able to compile and run the program, you have to add one external *tar file to your classpath. For this, click onto project –> property –> Java Build Path –> Libraries –> Add External JARs. In there, choose the java-json.jar, click on apply and close the window.
Now: Enter your username and password on top of the Main program, ensure that the correct server adress is entered and you can compile and run the program.
How does the connector work?
The connector consists of two parts: the main program and the OKAPI communication class. The latter one takes over the communication with OKAPI’s servers. This is actually the part that is most interesting for you, as the main program would be replaced by your software. The main program given in the git repository only serves as a dummy. In here, it simple gives some input data for the calculations to perform.
The communication is a three-step process. First, you authenticate yourself via Auth0 using OkapiConnector.init(). For this, you need to provide your username and password. If everything works fine, you get a token back, if not, an error is thrown. You find more details on the log-in issues in the error message.
Second, you send a request to OKAPI using OkapiConnector.sendRequest. All functions, requests and endpoints that are available are described in the API-Documentation. Note that we are currently introducing a “generic” API, which allows more flexible data types, which will be the standard in the future. Sending a request returns a request-id in the form of an UUID. Use this one, to get your result back from the server. This is achieved using the function OkapiConnector.getRequest. Always note that the server needs some time to process your request. So you can either wait a while until the request has been processed, or you simply try to get your result in a loop, until OkapiConnector.getRequestreturns a 200 as http response.