Package com.faircom.jsonaction

Class Session

  • public class Session
extends Object
    Manages the JSON Action API session on the FairCom server.
    • Manages server session settings including default values, timeouts, data formats, and debugging.
    • Manages the authToken returned by the API, which uniquely identifies and authorizes each session.
    • Use the post method to execute JSON actions in all FairCom JSON Action APIs.
    • Log out of a session as soon as you no longer need it.
    • Configure a java.util.logging.Logger to handle message logging.

    Typical builder/setter methods

    • username -- name of the account used by the server for authentication
    • password -- password used by the server to authenticate the account
    • databaseName -- connects to the database used by your application

    Optional builder/setter methods used mostly in production

    • ownerName ownerName} -- uses another account name instead of the username when querying and creating database objects
    • idleConnectionTimeoutSeconds -- configures the server when to detect and close an inactive session; 0 keeps a connection open
    • idleCursorTimeoutSeconds -- configures the server when to detect and close an inactive cursor; -1 keeps a cursor open
    • dataFormat -- causes the server to return data as an array of arrays (most efficient) or an array of objects (easier to process)
    • numberFormat -- causes the server to return numeric data as numbers or as strings containing numbers
    • binaryFormat -- identifies how binary data embedded in a JSON string is formatted, such as base64 or hex
    • description -- helps you identify a session

    Optional builder/setter methods used mostly in development

    • debug -- causes the server to return extra debug data in its responses
    • loggerLevel -- sets the logging level of this Java driver
    • defaultApi -- sets the default FairCom API used in the session -- rarely needed
    • authToken -- creates a session using an authToken from another session

    Uses

    Used by

    Example 

       ServerConnection serverConnection = new ServerConnection()
     .endpoint( "https://localhost:8443/api" )
     .caCertificatePath( "/FairCom/ca.crt" )
     .build();
   Session session = new Session()
     .serverConnection( serverConnection )
     .username( USER )
     .password( PASS )
     .databaseName( "ctreeSQL" )
     .numberFormat( Session.NumberFormat.NUMBER )
     .dataFormat( Session.DataFormat.OBJECTS )
     .build();
   DbApi dbApi = new DbApi( session );
   ObjectNode listDatabasesResult = dbApi.listDatabases( null, null ).get( "result" ).get( "data" );
   // Process the list of databases...
    To create a Jackson ObjectNode and set it to override properties for a unique request (in this case, return arrays instead of objects): 
       ObjectMapper objectMapper = new ObjectMapper();
   ObjectNode override = objectMapper.createObjectNode().set( "responseOptions", objectMapper.createObjectNode().put( "dataFormat", "ARRAYS" ) );
   ObjectNode listTablesResponse = dbApiUnderTest.listTables( "ctreeSQL", null, override );
   // Process the list of tables...

    • Constructor Detail

      • Session

        public Session()
        Create a Session object that connects to the FairCom server using the specified API Endpoint, username, and password. Use requestOverride to set session settings.
        Since:
        1.0

    • Method Detail

      • serverConnection

        public Session serverConnection​(ServerConnection serverConnection)
        Attaches a ServerConnection instance to this class.
        Parameters:
        serverConnection - an implementation of ServerConnection.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • username

        public Session username​(String username)
        Typically used: sets the username to the name of an account that will own this session. The server will authenticate this account using the "password" method. All subsequent actions will be done under the authorization of this account. See "username" in FairCom Documentation
        Parameters:
        username - the account name to use for authentication and ownership of all objects.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • password

        public Session password​(String password)
        Typically used: Sets the password of the account. The server will authenticate the account using the "password". See "password" in FairCom Documentation
        Parameters:
        password - the password to use for authentication.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • databaseName

        public Session databaseName​(String databaseName)
        Sets the database name the session connects to. All actions running in this session use objects in this database. Use a method's databaseName property to specify a different database. You can later change this setting, by running the AdminApi.alterSession method. See "defaultDatabaseName" in FairCom Documentation
        Parameters:
        databaseName - the value to set as the default database name.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • ownerName

        public Session ownerName​(String ownerName)
        Sets the name of the account that owns this session action. It allows a session to use tables created by another account and to create tables that are owned by another account. Use this method to override the default behavior, which makes the username the owner of the session. You can later change this setting, by running the AdminApi.alterSession method. See "defaultOwnerName" in FairCom Documentation
        Parameters:
        ownerName - the values to set as the default owner name.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • debug

        public Session debug​(Session.DebugLevel debug)
        Sets the session's debug setting. All actions running in this session use this setting. If you want a specific action to use a different setting, add the "params.debug" property to the requestOverride parameter. You can later change this setting, by running the AdminApi.alterSession method. See "defaultDebug" in FairCom Documentation
        Parameters:
        debug - the debug level to set.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • binaryFormat

        public Session binaryFormat​(Session.BinaryFormat binaryFormat)
        Sets the session's binary format used to encode binary values in JSON strings. The default is base64. You must encode binary values in this format before you send them to the API. The API encodes binary data in this format when it returns data. All actions running in this session use this setting. If you want a specific action to return binary data encoded differently, add the "params.defaultResponseOptions.binaryFormat" property to the requestOverride parameter. You can later change this setting, by running the AdminApi.alterSession method. See "defaultBinaryFormat" in FairCom Documentation
        Parameters:
        binaryFormat - the binary format to set.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • dataFormat

        public Session dataFormat​(Session.DataFormat dataFormat)
        Sets the default data format.
        • The server can return data as an array of arrays or as an array of objects.
        • An array of arrays is efficient to generate and transmit over the network.
        • An array of objects is easier to parse.
        • All actions running in this session use this setting.
        • If you want a specific action to use a different setting, add the "params.defaultResponseOptions.dataFormat" property to the requestOverride parameter.
        • You can later change this setting, by running the AdminApi.alterSession method.
        • See "defaultDataFormat" in FairCom Documentation
        Parameters:
        dataFormat - the data format to set.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • numberFormat

        public Session numberFormat​(Session.NumberFormat numberFormat)
        Sets the number format to either number or string. Note: this will not take effect until the next createSession or alterSession action is called.
        Parameters:
        numberFormat - the format to set.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • authToken

        public Session authToken​(String authToken)
        Sets the authToken. Used to create a new Session instance without creating a new session.
        Parameters:
        authToken - the authToken to use for this Session instance.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • idleConnectionTimeoutSeconds

        public Session idleConnectionTimeoutSeconds​(int idleConnectionTimeoutSeconds)
        Sets how long a session can go without communication before the server drops the session.
        Parameters:
        idleConnectionTimeoutSeconds - how long a session can go without communication before the server drops the session.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • idleCursorTimeoutSeconds

        public Session idleCursorTimeoutSeconds​(int idleCursorTimeoutSeconds)
        Set how long a cursor can be active without being used before the server closes the cursor.
        Parameters:
        idleCursorTimeoutSeconds - how long a cursor can be active without being used before the server closes the cursor.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • defaultApi

        public Session defaultApi​(String defaultApi)
        Sets the default API.
        Parameters:
        defaultApi - the API to set.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • description

        public Session description​(String description)
        Sets the description for this session.
        Parameters:
        description - the description for this session.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • loggerLevel

        public Session loggerLevel​(Level loggerLevel)
        Sets the logger level.
        Parameters:
        loggerLevel - the minimum level a logger message must be in order to be logged.
        Returns:
        an updated Session instance.
        Since:
        1.0

      • build

        public Session build()
              throws ConnectionException,
                     IOException
        Returns a Session instance that has an established session with the server based on your settings.
        Returns:
        a configured Session instance.
        Throws:
        ConnectionException - when a new session cannot be created.
        IOException - if the TLS settings cannot be implemented.
        Since:
        1.0

      • post

        public ObjectNode post​(String jsonString)
                throws ApiException
        Calls the ServerConnection class to POST a JSON request to the FairCom JSON Action endpoint.
        Parameters:
        jsonString - a JSON-formatted String representing the JSON Action to perform.
        Returns:
        the response body from the FairCom server.
        Throws:
        ApiException - when the input object cannot be read or when a class member cannot be serialized.
        Since:
        1.0

      • getServerConnection

        public ServerConnection getServerConnection()
        Return the ServerConnection attached to this class, so it can be easily used by another ServerConnection instance.
        Returns:
        the ServerConnection attached to this class.
        Since:
        1.0

      • getUsername

        public String getUsername()
        Query this object for the username this session authenticated with.
        Returns:
        the username used when the session was created.
        Since:
        1.0

      • getIdleCursorTimeoutSeconds

        public Integer getIdleCursorTimeoutSeconds()
        Retrieves the idle cursor timeout value in seconds.

        This method returns the value of the idleCursorTimeoutSeconds property, which represents the duration in seconds after which an idle cursor will be closed.

        Returns:
        the idle cursor timeout value in seconds.
        Since:
        1.0

      • getIdleConnectionTimeoutSeconds

        public Integer getIdleConnectionTimeoutSeconds()
        Retrieves the idle connection timeout value in seconds.

        This method returns the value of the idleConnectionTimeoutSeconds property, which represents the duration in seconds after which an idle connection will be closed.

        Returns:
        the idle connection timeout value in seconds.
        Since:
        1.0

      • getDefaultApi

        public String getDefaultApi()
        Retrieves the default API value.

        This method returns the default API value, which represents the API that will be used by default.

        Returns:
        the default API value.
        Since:
        1.0

      • getAuthToken

        public String getAuthToken()
        Query this object for the authToken of the current session.
        Returns:
        the authToken returned by createSession, or provided to the constructor.
        Since:
        1.0

      • getDatabaseName

        public String getDatabaseName()
        Returns the default database name.
        Returns:
        the default database name.
        Since:
        1.0

      • getOwnerName

        public String getOwnerName()
        Get the default owner name.
        Returns:
        the default owner name.
        Since:
        1.0

      • getDebug

        public Session.DebugLevel getDebug()
        Returns the default debug level.
        Returns:
        the default debug level.
        Since:
        1.0

      • getBinaryFormat

        public Session.BinaryFormat getBinaryFormat()
        Returns the default binary format.
        Returns:
        the default binary format.
        Since:
        1.0

      • getDataFormat

        public Session.DataFormat getDataFormat()
        Returns the default data format.
        Returns:
        the default data format.
        Since:
        1.0

      • getNumberFormat

        public Session.NumberFormat getNumberFormat()
        Get the number format: number or string.
        Returns:
        the current number format.
        Since:
        1.0

      • getDescription

        public String getDescription()
        Get the description of the session.
        Returns:
        the description of the session.
        Since:
        1.0

      • setLoggerLevel

        public void setLoggerLevel​(Level level)
        Set this session's Logger to the specified level.
        Parameters:
        level - the Logger.Level to set this instance logger to.
        Since:
        1.0

      • getLoggerLevel

        public Level getLoggerLevel()
        Get the current level that this session's Logger is set to.
        Returns:
        the current Logger Level.
        Since:
        1.0

      • connect

        public void connect()
             throws IOException,
                    ConnectionException
        Configure this class and the ServerConnection class, using previously run setters.
        Throws:
        IOException - if the TLS settings cannot be implemented.
        ConnectionException - when a new session cannot be created.
        Since:
        1.0

      • describeThisSession

        public ObjectNode describeThisSession()
                               throws ApiException
        Returns information about the current session in a Jackson ObjectNode. This method uses the describeSessions action to get detailed information about the session from the server. This is useful when other clients might make changes to the session.
        Returns:
        The response from the describeSessions action, containing information about the session.
        Throws:
        ApiException - when an API error occurs.
        IllegalStateException - when there is no active connection.
        Since:
        1.0
        See Also:
        FairCom's describeSessions documentation

      • logoutThisSession

        public ObjectNode logoutThisSession()
                             throws ApiException
        Log out from FairCom server and release all session resources. WARNING! This method will log out all users of this instance's authToken! If the instance of this class was constructed using the "authToken constructor", calling this method will also log out the session which provided that authToken!
        Returns:
        the response from this request.
        Throws:
        ApiException - when the POST returns an HTTP code outside the 200 range.
        Since:
        1.0
        See Also:
        deleteSession documentation, AdminApi.deleteSession(String, ObjectNode)

      • buildBasicRequest

        public static ObjectNode buildBasicRequest​(String api,
                                           String authToken,
                                           String requestId)
        Build a FairCom JSON Action request containing most of the required properties for JSON Action APIs. Add more properties to the returned object before sending it to the FairCom server to further configure the JSON Action request.
        Parameters:
        api - the JSON Action APi to use.
        authToken - the authToken to use. Set to null when you do not want to specify an authToken.
        requestId - the requestId to use. Set to null when you do not want to specify a requestId.
        Returns:
        a ObjectNode representing the requested JSON Action.
        Since:
        1.0

      • merge

        public static void merge​(JsonNode mainNode,
                         JsonNode updateNode)
        Merge the contents of updateNode into mainNode. Properties which already exist in mainNode will be overridden by matching properties from updateNode. The contents of updateNode will not be changed.
        Parameters:
        mainNode - the JsonNode to merge data into.
        updateNode - the JsonNode to merge into mainNode.
        Since:
        1.0

      • toJson

        public String toJson()
        Convert the current object to a JSON string.
        Returns:
        the JSON string representation of the object.
        Since:
        1.0

      • reconnect

        public void reconnect()
               throws ApiException
        Reconnects to the server by testing the existing ServerConnection instance and creating a new session if necessary.
        Throws:
        ApiException - if there is an error during the reconnection process.
        ConnectionException - if unable to make a connection to the endpoint.
        Since:
        1.0