Onyx Database Restful Web Persistence

Restful Web Persistence
A Restful Web Onyx Database tutorial
This guide walks you through how to set up Onyx Database to interact with Restful Web Services using an Objective C client. You will notice that working with Onyx Database's Restful API is similar in nature to working with CoreData.

You can download the code for this example here: OnyxDevTools/onyx-database-samples/restful-web-persistence-manager.

Why Use?

A Restful Persistence API is used to connect and interact to an Onyx Database just as you would with any other Restful Web Service.

You would use the Onyx Restful Web Server if you need to have interoperability with various clients written in other languages such as Objective C, NodeJS, Ruby, PHP, Android, ExtJS, HTML5, Python, or any technology that supports web services.

Here is an example of how to write an iPhone client to consume an Onyx Database web service:

Project 1: The Database Server

  1. Create a jar project that will be launched as a database server
    A complete pom.xml can be seen here
    Make sure to include onyx-remote-database.jar and the data-model.jar you created earlier as dependences.
    You do not need to include onyx-database.jar; it will automatically be include because it is a transitive dependency of onyx-remote-database.jar
  2. Create a main method

    The main method will configure and create a running instance of the database server.

    Specify a port to listen to
    Specify a local path to store your binary data
    It's a pretty good idea to set security credentials. If you do not they will default to: admin/admin
    Start the database server. This will initiate a running background thread, which your server application can join
  3. Now you can start you database server

    Navigate to the queryRootDirectory directory of the database server project, and run the following command:

  4. Create a web service client with Objective C

Project 2: The Client

  1. Create a new XCode Project

    1. In XCode, go to File > New > Project ...
    2. Select Single View Application as the application type.
    3. Name the project "OnyxDatabaseClientExample".

    Screenshot of selecting single view within XCode
  2. Download onyx-database-client-cocoapod from Onyx Dev Tools Web Service Client Downloads Page.
    Place this client application into a folder called "Pods" in your Xcode project directory.
  3. Create a new Podfile in the queryRootDirectory directory as your Xcode project.
    Include the path to the onyx-database-client-cocoapod directory
  4. Quit Xcode, open your console, then navigate to the parent directory of your Podfile and run the following command:
    This will download your dependencies, install your pod, and generate a workspace file.
  5. Edit your AppDelegate to configure the database connection and instantiate the persistenceManager
    The persistenceManager is an auto-generated wrapper that you will use to interact with Onyx Database's Restfull API.
    Set the username, password and host.
    Remember to use apiWithHeader, which sets the authorization token.
  6. Modify Info.plist to disable App Transport Security (ATS)
    Apple requires that you use https for external APIs. Disabling ATS should not be a used for production implementation.
  7. Create a corresponding Objective C class for the Person entity.
    Your Objective C entity classes must extend SWGObject
    All of the the Objective C attributes should be named the same as the Java attributes.
  8. Add IBActions to the ViewController for saving, querying and finding the Person records.
    For each call, invoke the Onyx Database API persistenceManager method with a completion block that handles the response.
  9. In Project navigator, select the Main.storyboard and create Buttons with Action Connections to the IBActions in your ViewController. Connect IBActions within Main.storyboard
  10. Now your application is ready to launch and interact with your running database server!
  11. Persisting Data