Java SDK - Overview

Java SDK for Catalyst paves the way for creating microservices, interactive web and mobile applications with Java programming elements and associating them with catalyst components. The SDK offers the necessary structures to access the Catalyst APIs comfortably. It acts as a wrapper for the REST APIs and helps you use Catalyst services effectively.

Catalyst currently supports the following versions of Java:

  • Java 8
  • Java 11
  • Java 17

Initialize Project

To initialize Catalyst project, add the code snippet below to your Java source code as the very first statement, before you start writing your business logic.

Note: In Java SDK it is not mandatory to include this initialize command as it will be automatically initialized in functions.

Initialize Catalyst Projects with Specific SDK Scopes

Catalyst allows you to initialize a project using the following scopes:

  • Admin: You have unrestricted access to all the components and their respective functionalities. For example, you have complete access to the Data Store to perform all operations like Read, Write, Delete, etc.

  • User: You can restrict access to components, and specific functionalities. For example, you can provide Read access alone to Data Store.

  • It is not mandatory for you to initialize the projects with scopes. By default, a project that is initialized will have Admin privileges.

  • Ensure you have initialized the Catalyst SDK with the appropriate scope while you engineer your business logic. The permissions you define for your scope control your end-user’s actions.

  • Scopes only apply to operations related Data Store, File Store, and ZCQL.

  • Depending on how you engineer your business logic, you can decide if your end-users can perform Admin or User actions. This is decided based on the role assigned to your end-user when they sign up to your application in Catalyst Authentication. The permissions for the roles can be configured in the Scopes & Permissions section of the Data Store and File store.

The SDK snippets below will allow you to initialize the project using either Admin or User scope, and perform a SELECT query in the Data Store:

  • Initialize the Catalyst project with Admin Scope
ZCProject adminProject = ZCProject.initProject("admin", ZCUserScope.ADMIN); ZCQL.getInstance(adminProject).executeQuery("select * from test");
  • Initialize the Catalyst project with User Scope
ZCProject userProject = ZCProject.initProject("user", ZCUserScope.USER); ZCQL.getInstance().executeQuery("select * from test");

Class Hierarchy

All the Catalyst components are modelled as Java classes with their members and methods defining the behaviour of the component.

  • ZCProject is the fundamental base class of the SDK package. It has methods to initialize the catalyst project configurations and associate the components of the project.
  • The class relations and hierarchy of the SDK follow the project hierarchy in Catalyst.
  • Each class has functions to fetch its properties and to fetch the data of its immediate child entities through an API call. For example, a Catalyst Data Store class, ZCDataStore will have member functions to access tables that can use the functions of its immediate child class ZCTable to set the table name, ID, etc.

The class hierarchy of various Catalyst components is depicted as:


Instance Objects

It is not always effective to follow the class hierarchy all the way from the top to fetch the data of a component at a lower level, since this would involve API calls at every level. In order to avoid this, every component class has a getInstance() method to get its dummy object and methods to get dummy objects of its child entities.

Note: getInstance() methods will not have any of their properties filled in since no API call will be made. This will just return a dummy object that will be only used to access the non-static methods of the class.

To retrieve the properties of a Catalyst component, call the component’s object with its getInstance() method, then use the same object to call the other methods defined by the component. This avoids unnecessary API calls.


Unexpected faulty behaviours are called exceptions. All errors and exceptions are handled by a class called ZCException defined by our Java SDK. We have ZCServerException and ZCClientException classes to catch the specific exceptions thrown by the client and server codes.

Last Updated 2023-09-08 15:47:48 +0530 +0530