Package uk.co.sculptor.kflibjava

Class Server

java.lang.Object
uk.co.sculptor.kflibjava.Server
All Implemented Interfaces:
AutoCloseable
public class Server extends Object implements AutoCloseable

Represents the KfServer connection and is the basic object needed to work with the kflibjava library.

Note: This class implements the AutoCloseable interface, meaning that an object may hold resources (such as file or socket handles) until it is closed. The close() method of an AutoCloseable object is called automatically when exiting a try-with-resources block for which the object has been declared in the resource specification header. This construction ensures prompt release, avoiding resource exhaustion exceptions and errors that may otherwise occur.
Author:
Marcos Gutierrez Batz

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Server.CopyOption
    Enumerator flags used to specify the copyFile options.
    static enum 
    Server.ExecFlag
    Enumerator flags used to specify the executed process flags on the Server.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Server(String serverName)
    Constructor: Create the Server object connected to specified serverName using default timeOut.
    Server(String serverName, int timeOut)
    Constructor: Create the Server object connected to specified serverName.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    auditDatabase(String auditDatabase)
    Method to setup the audit database to be used Functionality: - The method sets the current audit database to use - Must be used before any keyed file access or any other audit_* method so that the correct database must be modified
    void
    auditDisableDatabase(String auditDatabase)
    Method to disable the audit database Functionality: - If the database object is already created: + Closes all that auditDb files + Changes the audit database to be disabled at the server level - If the database object is not created: + Creates a database object on the server with no file opened and flagged as disabled - The execution of the method waits for the command completion **Note:** This method is only supported by server version 6.1 or greater.
    void
    auditEnableDatabase(String auditDatabase)
    Method to enable the audit database Functionality: - If the database object is already created: + Opens all that auditDb files + Changes the audit database to be enabled at the server level - If the database object is not created: + Creates a database object on the server + Opens the auditDb files + Flag the database as enabled - The execution of the method waits for the command completion **Note:** This method is only supported by server version 6.1 or greater.
    boolean
    auditFreeze(boolean freeze)
    Method called when wanting to freeze the audit service **Note:** This method is only supported by server version 6.1 or greater.
    String
    auditSwitchDatabase(String auditDatabase)
    Method to switch the audit database so that the old one is archived Functionality: - First close the auditDb files: auditrecord, auditfields and transactions - Queue all pending audit writes - Move the files to the archive location: auditDb/archive/date_time (the relocation service can be used.
    void
    auditTransaction()
    Method to define a new audit transaction Functionality: - The method sets the custom values in the transaction record (if specified)
    void
    auditTransaction(String cv1)
    Method to define a new audit transaction specifying one custom value Functionality: - The method sets the custom values in the transaction record (if specified)
    void
    auditTransaction(String cv1, String cv2)
    Method to define a new audit transaction specifying two custom values Functionality: - The method sets the custom values in the transaction record (if specified)
    void
    auditTransaction(String cv1, String cv2, String cv3)
    Method to define a new audit transaction specifying three custom values Functionality: - The method sets the custom values in the transaction record (if specified)
    void
    auditTransaction(String cv1, String cv2, String cv3, String cv4)
    Method to define a new audit transaction specifying four custom values Functionality: - The method sets the custom values in the transaction record (if specified)
    void
    changePasswordKFServer(String pass)
    Change the previously logged user password on the server.
    void
    close()
    Close all Databases hanging from the server and close the server connection.
    int
    copyFile(String srcFileOnServer, Server dstServer, String dstFileOnServer, EnumSet<Server.CopyOption> options)
    Copy the source file on the current Server to the destination file on the destination server
    byte
    getFix64()
    Returns the server fix64 flag
    byte
    getIsDos()
    Returns whether the server is in a Windows platform
    int
    getMaxUsers()
    Returns maxUsers
    Realm
    getRealm()
    Method to return the parent Realm when it exists.
    int
    getScDateVers()
    Returns scDateVers
    int
    getScFixVers()
    Returns Sculptor Fix Version
    int
    getScMainVers()
    Returns Sculptor Main Version
    int
    getScSubVers()
    Returns Sculptor Sub Version
    String
    getSculptorDir()
    Returns Server Sculptor Directory
    String
    getServerName()
    Returns Server Name
    int
    getSrvMainVers()
    Returns server Main Version (before Sc61 was different to Sculptor version)
    int
    getSrvSubVers()
    Returns server Sub Version (before Sc61 was different to Sculptor version)
    void
    loginKFServer(String login, String pass)
    Login as a user on the server.
    int
    makeDir(String directory, short mode)
    Create a directory on the server.
    void
    mirrorDisable(String filename)
    Method to disable a mirror database Functionality: - The call is based in a normal file that happens to be mirrored due the server configuration - After disabled, the mirrored files that use the same mirror source and flags, won't be mirrored when opened **Note:** This method is only supported by server version 6.2 or greater.
    void
    mirrorEnable(String filename)
    Method to enable a mirror database Functionality: - The call is based in a normal file that happens to be mirrored due the server configuration - After enabled, the mirrored files that use the same mirror source and flags, will be mirrored when opened as normal **Note:** This method is only supported by server version 6.2 or greater.
    Database
    openDB(String databaseName, Database.Type type)
    Creates a Database object.
    Database
    openDB(String databaseName, Database.Type type, EnumSet<Database.Flag> flags)
    Creates a Database object.
    Database
    openDB(String databaseName, Database.Type type, EnumSet<Database.Flag> flags, String source, int riuTimeout, String logFile)
    Creates a Database object.
    ServerFile
    openServerFile(String fileOnServer)
    Create a ServerFile object that represents a remote file on the Server.
    void
    processCloseHandle(long processHandle)
    A handle should be closed when it is no longer needed in order to free resources.
    void
    processEnd(long processHandle, int exitCode)
    Terminate a process.
    long
    processExecute(String command, String directory, EnumSet<Server.ExecFlag> flags)
    The child process runs asynchronously with its parent.
    int
    processExitCode(long processHandle, long waitMilliSecs)
    Return the exit code of a process.
    void
    sendKeepAlive(long intervalSecs)
    Send Keep Alive to the server.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

  • Method Details

    • auditDatabase

      public void auditDatabase(String auditDatabase) throws IOException, KfException
      Method to setup the audit database to be used Functionality: - The method sets the current audit database to use - Must be used before any keyed file access or any other audit_* method so that the correct database must be modified. - The audit database keyed files will be located inside $SCULPTOR/audit/auditDatabase **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Parameters:
      auditDatabase - Audit database name.
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • auditDisableDatabase

      public void auditDisableDatabase(String auditDatabase) throws IOException, KfException
      Method to disable the audit database Functionality: - If the database object is already created: + Closes all that auditDb files + Changes the audit database to be disabled at the server level - If the database object is not created: + Creates a database object on the server with no file opened and flagged as disabled - The execution of the method waits for the command completion **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Parameters:
      auditDatabase - Audit database name.
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • auditEnableDatabase

      public void auditEnableDatabase(String auditDatabase) throws IOException, KfException
      Method to enable the audit database Functionality: - If the database object is already created: + Opens all that auditDb files + Changes the audit database to be enabled at the server level - If the database object is not created: + Creates a database object on the server + Opens the auditDb files + Flag the database as enabled - The execution of the method waits for the command completion **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Parameters:
      auditDatabase - Audit database name.
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • auditFreeze

      public boolean auditFreeze(boolean freeze) throws IOException, KfException
      Method called when wanting to freeze the audit service **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Parameters:
      freeze - Whether to freeze or unfreeze
      Returns:
      the previous audit service freeze value
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • auditSwitchDatabase

      public String auditSwitchDatabase(String auditDatabase) throws IOException, KfException
      Method to switch the audit database so that the old one is archived Functionality: - First close the auditDb files: auditrecord, auditfields and transactions - Queue all pending audit writes - Move the files to the archive location: auditDb/archive/date_time (the relocation service can be used. But take into account that the destination location must be on the SAME file system for the movement to be quick!!!) - Recreate new audit* and transaction files (empty) - Open original transaction file in read only mode (the moved one) - Check all the server threads, and for each thread that has a transaction open, read the transaction on the original transaction file and write it to the new transaction file - Then close the old moved transaction file - And continue to process the audit command queue. We're back into normal operation - The archive directory name created is returned (relative to auditDb dir) **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Parameters:
      auditDatabase - Audit database name (when empty means current thread audit database)
      Returns:
      the archive directory where the audit files have been moved
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • auditTransaction

      public void auditTransaction() throws IOException, KfException
      Method to define a new audit transaction Functionality: - The method sets the custom values in the transaction record (if specified). - Used to trigger the creation of a new transaction when an audit record must be created. - If no audit record is created no transaction is created (no need to have empty transactions). **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • auditTransaction

      public void auditTransaction(String cv1) throws IOException, KfException
      Method to define a new audit transaction specifying one custom value Functionality: - The method sets the custom values in the transaction record (if specified). - Used to trigger the creation of a new transaction when an audit record must be created. - If no audit record is created no transaction is created (no need to have empty transactions). **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Parameters:
      cv1 - Audit transaction CustomValue1 field value
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • auditTransaction

      public void auditTransaction(String cv1, String cv2) throws IOException, KfException
      Method to define a new audit transaction specifying two custom values Functionality: - The method sets the custom values in the transaction record (if specified). - Used to trigger the creation of a new transaction when an audit record must be created. - If no audit record is created no transaction is created (no need to have empty transactions). **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Parameters:
      cv1 - Audit transaction CustomValue1 field value
      cv2 - Audit transaction CustomValue2 field value
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • auditTransaction

      public void auditTransaction(String cv1, String cv2, String cv3) throws IOException, KfException
      Method to define a new audit transaction specifying three custom values Functionality: - The method sets the custom values in the transaction record (if specified). - Used to trigger the creation of a new transaction when an audit record must be created. - If no audit record is created no transaction is created (no need to have empty transactions). **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Parameters:
      cv1 - Audit transaction CustomValue1 field value
      cv2 - Audit transaction CustomValue2 field value
      cv3 - Audit transaction CustomValue2 field value
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • auditTransaction

      public void auditTransaction(String cv1, String cv2, String cv3, String cv4) throws IOException, KfException
      Method to define a new audit transaction specifying four custom values Functionality: - The method sets the custom values in the transaction record (if specified). - Used to trigger the creation of a new transaction when an audit record must be created. - If no audit record is created no transaction is created (no need to have empty transactions). **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Parameters:
      cv1 - Audit transaction CustomValue1 field value
      cv2 - Audit transaction CustomValue2 field value
      cv3 - Audit transaction CustomValue3 field value
      cv4 - Audit transaction CustomValue4 field value
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • changePasswordKFServer

      public void changePasswordKFServer(String pass) throws IOException, KfException
      Change the previously logged user password on the server. **Note:** This method is only supported by server version 6.1 or greater. Otherwise a KfException is raised.
      Parameters:
      pass - Password to check on server.
      Throws:
      IOException - If an I/O error occurs when creating the socket.
      KfException - Any error on the KfServer protocol or user name/password error.

    • close

      public void close() throws IOException, KfException
      Close all Databases hanging from the server and close the server connection.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException - If an I/O error occurs when dealing with the socket
      KfException - Any error on the KfServer protocol or on the server closing process.

    • copyFile

      public int copyFile(String srcFileOnServer, Server dstServer, String dstFileOnServer, EnumSet<Server.CopyOption> options) throws IOException, KfException
      Copy the source file on the current Server to the destination file on the destination server
      Parameters:
      srcFileOnServer - Local file on current object (this) to copy on the dstServer.
      dstServer - Server where to copy the file. If this parameter is null or the same local object (this) the a remote server file copy is issued.
      dstFileOnServer - Local file on dstServer where to copy the srcFileOnServer.
      options - One or more of the Server.CopyOption flags ored together.
      Returns:
      return 0 if the file is not copied or 1 otherwise.
      Throws:
      IOException - If an I/O error occurs when creating the socket.
      KfException - Any error on the KfServer protocol or user name/password error.

    • getFix64

      public byte getFix64()
      Returns the server fix64 flag
      Returns:
      the server fix64 flag

    • getIsDos

      public byte getIsDos()
      Returns whether the server is in a Windows platform
      Returns:
      whether the server is in a Windows platform

    • getMaxUsers

      public int getMaxUsers()
      Returns maxUsers
      Returns:
      maxUsers

    • getScDateVers

      public int getScDateVers()
      Returns scDateVers
      Returns:
      scDateVers

    • getScFixVers

      public int getScFixVers()
      Returns Sculptor Fix Version
      Returns:
      Sculptor Fix Version

    • getScMainVers

      public int getScMainVers()
      Returns Sculptor Main Version
      Returns:
      Sculptor Main Version

    • getScSubVers

      public int getScSubVers()
      Returns Sculptor Sub Version
      Returns:
      Sculptor Sub Version

    • getSculptorDir

      public String getSculptorDir()
      Returns Server Sculptor Directory
      Returns:
      Server Sculptor Directory

    • getServerName

      public String getServerName()
      Returns Server Name
      Returns:
      Server Name

    • getSrvMainVers

      public int getSrvMainVers()
      Returns server Main Version (before Sc61 was different to Sculptor version)
      Returns:
      server Main Version (before Sc61 was different to Sculptor version)

    • getSrvSubVers

      public int getSrvSubVers()
      Returns server Sub Version (before Sc61 was different to Sculptor version)
      Returns:
      server Sub Version (before Sc61 was different to Sculptor version)

    • getRealm

      public Realm getRealm()
      Method to return the parent Realm when it exists.
      Returns:
      the realm

    • loginKFServer

      public void loginKFServer(String login, String pass) throws IOException, KfException
      Login as a user on the server.
      Parameters:
      login - User name to check the password on the server.
      pass - Password to check on server.
      Throws:
      IOException - If an I/O error occurs when creating the socket.
      KfException - Any error on the KfServer protocol or user name/password error.

    • makeDir

      public int makeDir(String directory, short mode) throws IOException, KfException
      Create a directory on the server. The directory parent must exist.
      Parameters:
      directory - Path to create on the server.
      mode - Unix type of permissions used to create directories with.
      Returns:
      when the directory is created return 1 when not created return 0.
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol.

    • mirrorDisable

      public void mirrorDisable(String filename) throws IOException, KfException
      Method to disable a mirror database Functionality: - The call is based in a normal file that happens to be mirrored due the server configuration - After disabled, the mirrored files that use the same mirror source and flags, won't be mirrored when opened **Note:** This method is only supported by server version 6.2 or greater. Otherwise a KfException is raised.
      Parameters:
      filename - Keyed filename that may be mirrored on the server.
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • mirrorEnable

      public void mirrorEnable(String filename) throws IOException, KfException
      Method to enable a mirror database Functionality: - The call is based in a normal file that happens to be mirrored due the server configuration - After enabled, the mirrored files that use the same mirror source and flags, will be mirrored when opened as normal **Note:** This method is only supported by server version 6.2 or greater. Otherwise a KfException is raised.
      Parameters:
      filename - Keyed filename that may be mirrored on the server.
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - Any error on the KfServer protocol, on the server process or on system socket

    • openDB

      public Database openDB(String databaseName, Database.Type type) throws KfException, IOException
      Creates a Database object. **Note:** This method only supports ODBC databases with server version 6.0 or greater. Otherwise a KfException is raised.
      Parameters:
      databaseName - Database name
      type - Database type (see Database.Type)
      Returns:
      the Database object to be used to create KeyedFiles
      Throws:
      KfException - Any error on the KfServer protocol or parameters.
      IOException - If an I/O error occurs when using the socket.

    • openDB

      public Database openDB(String databaseName, Database.Type type, EnumSet<Database.Flag> flags) throws KfException, IOException
      Creates a Database object.
      Parameters:
      databaseName - Database name
      type - Database type (see Database.Type)
      flags - Database flag (see Database.Flag)
      Returns:
      the Database object to be used to create KeyedFiles
      Throws:
      KfException - Any error on the KfServer protocol or parameters.
      IOException - If an I/O error occurs when using the socket.

    • openDB

      public Database openDB(String databaseName, Database.Type type, EnumSet<Database.Flag> flags, String source, int riuTimeout, String logFile) throws KfException, IOException
      Creates a Database object.
      Parameters:
      databaseName - Database name
      type - Database type (see Database.Type)
      flags - Database flag (see Database.Flag)
      source - Database source string (can be the directory where the key files are relative to)
      riuTimeout - Record In Use timeout
      logFile - Log file to be used on server
      Returns:
      theDatabase object to be used to create KeyedFiles
      Throws:
      KfException - Any error on the KfServer protocol or parameters.
      IOException - If an I/O error occurs when using the socket.

    • openServerFile

      public ServerFile openServerFile(String fileOnServer) throws IOException, KfException
      Create a ServerFile object that represents a remote file on the Server.
      Parameters:
      fileOnServer - Path name of the file on the Server
      Returns:
      the object that represents the remote file.
      Throws:
      IOException - If an I/O error occurs when using the socket.
      KfException - Any error on the KfServer protocol or parameters.

    • processCloseHandle

      public void processCloseHandle(long processHandle) throws IOException, KfException
      A handle should be closed when it is no longer needed in order to free resources.
      Parameters:
      processHandle - The remote process handle as returned by processExecute(String, String, EnumSet).
      Throws:
      IOException - If an I/O error occurs when dealing with the socket
      KfException - Any error on the KfServer protocol or any operation.

    • processEnd

      public void processEnd(long processHandle, int exitCode) throws IOException, KfException
      Terminate a process.
      Parameters:
      processHandle - The remote process handle as returned by processExecute(String, String, EnumSet).
      exitCode - Required exit code
      Throws:
      IOException - If an I/O error occurs when dealing with the socket
      KfException - Any error on the KfServer protocol or any operation.

    • processExecute

      public long processExecute(String command, String directory, EnumSet<Server.ExecFlag> flags) throws IOException, KfException
      The child process runs asynchronously with its parent. Use the processExitCode(long, long) method to determine when the child process terminates. Call the processCloseHandle(long) method when the returned handle is no longer needed.
      Parameters:
      command - Command to be executed
      directory - Directory in which the command is to be executed.
      flags - One or more of the Server.ExecFlag flags ored together.The flags are for use on Windows systems. Use NONE on Unix and Linux and for a standard Windows child process.
      Returns:
      Returns the handle that can be used with the methods processCloseHandle(long), processEnd(long, int) and processExitCode(long, long).
      Throws:
      IOException - If an I/O error occurs when dealing with the socket
      KfException - Any error on the KfServer protocol or any operation.

    • processExitCode

      public int processExitCode(long processHandle, long waitMilliSecs) throws IOException, KfException
      Return the exit code of a process.
      Parameters:
      processHandle - The remote process handle as returned by processExecute(String, String, EnumSet).
      waitMilliSecs - Milliseconds to wait for the process to end.
      Returns:

      -3: Process still running.
      -2: Process terminated by interrupt.
      -1: Invalid process_id or no permission. (not returned as a KfException is thrown)
      0-255: Process exit code.
      Throws:
      IOException - If an I/O error occurs when dealing with the socket
      KfException - Any error on the KfServer protocol or any operation.

    • sendKeepAlive

      public void sendKeepAlive(long intervalSecs) throws IOException, KfException
      Send Keep Alive to the server.
      Parameters:
      intervalSecs - Keep Alive interval
      Throws:
      IOException - Any error received by writing/reading the socket.
      KfException - When a protocol error or a server error is detected.