Package tech.oxfordsemantic.jrdfox.client

Interface ServerConnection

All Superinterfaces:
java.lang.AutoCloseable
public interface ServerConnection
extends java.lang.AutoCloseable
Encapsulates a connection to an RDFox server. All instances of this class are single-threaded — that is, no method should be called simultaneously on several threads. However, please note that there is no thread affinity — that is, methods on one connection can be called from different threads as long as the calls are serialised externally. externally. The interrupt(), duplicate(), and checkPassword(String password) methods are exceptions: they can be invoked in parallel with any other method apart from close(). Calling close() in parallel with any other method will almost certainly crash the JVM. Multiple connections should be used to access a server concurrently, in which case all access to the server is serialised. A connection must be closed after use to release the resources associated with it.

  • Field Summary

    Fields 
    Modifier and Type Field Description
    static byte ACCESS_TYPE_GRANT
    A flag specifying grant access to a resource.
    static byte ACCESS_TYPE_NONE
    A flag specifying no access to a resource.
    static byte ACCESS_TYPE_READ
    A flag specifying read access to a resource.
    static byte ACCESS_TYPE_STAR
    A flag specifying all access types to a resource.
    static byte ACCESS_TYPE_WRITE
    A flag specifying write access to a resource.

  • Method Summary

    Modifier and Type Method Description
    void changeRolePassword​(java.lang.String currentPassword, java.lang.String newPassword)
    Creates the password of the role that is associated with this connection.
    void checkPassword​(java.lang.String password)
    Checks whether the supplied password is valid for the role associated with this connection.
    void close()
    Closes the data store connection by freeing all resources associated with it.
    boolean containsDataStore​(java.lang.String dataStoreName)
    Returns true if the connected server contains a data store with the given name.
    void createDataStore​(java.lang.String dataStoreName, java.util.Map<java.lang.String,​java.lang.String> dataStoreParameters)
    Creates a data store with the given name.
    void createRole​(java.lang.String roleName, java.lang.String password)
    Creates a new role with the given name and password.
    void createRole​(java.lang.String roleName, java.lang.String passwordOrHash, boolean isHash)
    Creates a new role with the given name and password.
    void deleteDataStore​(java.lang.String dataStoreName)
    Deletes a data store with the given name from the server.
    void deleteDataStore​(java.lang.String dataStoreName, java.lang.String expectedDataStoreUniqueID, long expectedDataStoreVersion)
    Deletes a data store with the given name from the server if the data store's unique ID and version match the expected values.
    void deleteRole​(java.lang.String roleName)
    Deletes a role with the given name.
    ServerConnection duplicate()
    Creates a new connection to the same data store.
    ComponentInfo getComponentInfo​(boolean extended)
    Returns diagnostic information about the server as a tree of objects each providing detailed information about the server.
    java.lang.String getGitSHA()
    Returns the string containing the Git SHA identifying the precise version of the RDFox instance code.
    long[] getMemoryUse()
    Returns the current memory use of RDFox.
    int getNumberOfThreads()
    Returns the number of threads that the server uses for various tasks such as reasoning and data importation.
    java.util.Map<java.lang.String,​java.lang.String> getParameters()
    Returns the parameters that the server was created with.
    java.lang.String getRoleName()
    Returns the name of the role currently associated with this connection.
    java.lang.String getRolePasswordHash​(java.lang.String roleName)
    Returns the password hash for the given role name.
    java.lang.String getVersion()
    Returns the version string of the RDFox instance.
    boolean grantPrivileges​(java.lang.String roleName, java.lang.String resourceSpecifier, byte accessTypesToGrant)
    Grants privileges over a resource specifier to a role.
    boolean grantRole​(java.lang.String roleName, java.lang.String superRoleName)
    Grants the membership of a role in another role.
    void interrupt()
    Tries to interrupt an operation that is running in parallel on this connection.
    boolean isMemberOf​(java.lang.String roleName, java.lang.String superRoleName)
    Checks whether the given role is a member of another super-role.
    java.util.List<java.lang.String> listDataStores()
    Returns the list of names of data stores available at the connected server.
    java.util.Map<java.lang.String,​java.lang.Byte> listPrivileges​(java.lang.String roleName)
    Lists the privileges of a given role.
    java.util.List<java.lang.String> listRoleMembers​(java.lang.String roleName)
    Lists the roles that are members of the given role.
    java.util.List<java.lang.String> listRoleMemberships​(java.lang.String roleName)
    Lists the roles that the given role is a member of.
    java.util.List<java.lang.String> listRoles()
    Returns the list of all roles available at the server.
    void loadDataStoreFromBinaryFormat​(java.lang.String dataStoreName, java.io.File file)
    Loads a data store with the given name from a file containing the store saved in the standard or raw format.
    void loadDataStoreFromBinaryFormat​(java.lang.String dataStoreName, java.io.File file, java.util.Map<java.lang.String,​java.lang.String> dataStoreParameters)
    Loads a data store with the given name from a file containing the store saved in the standard or raw format.
    void loadDataStoreFromBinaryFormat​(java.lang.String dataStoreName, java.io.InputStream inputStream)
    Loads a data store with the given name from an input stream containing the store saved in the standard or raw format.
    void loadDataStoreFromBinaryFormat​(java.lang.String dataStoreName, java.io.InputStream inputStream, java.util.Map<java.lang.String,​java.lang.String> dataStoreParameters)
    Loads a data store with the given name from an input stream containing the store saved in the standard or raw format.
    DataStoreConnection newDataStoreConnection​(java.lang.String dataStoreName)
    Creates a connection to the data store of this server with the given name.
    boolean revokePrivileges​(java.lang.String roleName, java.lang.String resourceSpecifier, byte accessTypesToRevoke)
    Revokes privileges over a resource specifier from a role.
    boolean revokeRole​(java.lang.String roleName, java.lang.String superRoleName)
    Revokes the membership of a role in another role.
    void saveDataStoreToBinaryFormat​(java.lang.String dataStoreName, java.io.File file, BinaryDataStoreFormat format)
    Saves a data store into the specified binary format.
    void saveDataStoreToBinaryFormat​(java.lang.String dataStoreName, java.io.OutputStream outputStream, BinaryDataStoreFormat format)
    Saves a data store into the specified binary format.
    void saveDataStoreToBinaryFormat​(java.lang.String dataStoreName, java.lang.String expectedDataStoreUniqueID, long expectedDataStoreVersion, java.io.File file, BinaryDataStoreFormat format)
    Saves a data store into the specified binary format if the data store's unique ID and version match the expected values.
    void saveDataStoreToBinaryFormat​(java.lang.String dataStoreName, java.lang.String expectedDataStoreUniqueID, long expectedDataStoreVersion, java.io.OutputStream outputStream, BinaryDataStoreFormat format)
    Saves a data store into the specified binary format if the data store's unique ID and version match the expected values.
    void setMaxMemoryUse​(long maxUsedBytes)
    Sets the maximum amount of memory that RDFox is allowed to use.
    void setNumberOfThreads​(int numberOfThreads)
    Sets the number of threads that the server should use for various tasks such as reasoning and data importation.

  • Field Details

  • Method Details

    • close

      void close()
      Closes the data store connection by freeing all resources associated with it. Once a connection is closed, it cannot be used any further. Calling this method in parallel with any other method runs a very high risk of crashing the JVM.
      Specified by:
      close in interface java.lang.AutoCloseable

    • duplicate

      ServerConnection duplicate() throws JRDFoxException
      Creates a new connection to the same data store. The new connection inherits the role name from this one. The main use of this method is to avoid having to specify the role credentials again.
      Returns:
      a new connection to the same server
      Throws:
      JRDFoxException - thrown if an error is encountered

    • interrupt

      void interrupt() throws JRDFoxException
      Tries to interrupt an operation that is running in parallel on this connection. RDFox will make a best effort to interrupt an operation, but there are no guarantees that the operation will indeed be interrupted. An operation will throw an OperationInterruptedException exception. This method can be called concurrently with any other method apart from close().
      Throws:
      JRDFoxException - thrown if an error is encountered

    • getRoleName

      java.lang.String getRoleName() throws JRDFoxException
      Returns the name of the role currently associated with this connection.
      Returns:
      the name of the role currently associated with this connection
      Throws:
      JRDFoxException - thrown if there is an error

    • checkPassword

      void checkPassword​(java.lang.String password) throws JRDFoxException
      Checks whether the supplied password is valid for the role associated with this connection. On failure, an exception is thrown and the connection remains valid.
      Parameters:
      password - the password of the new user
      Throws:
      JRDFoxException - thrown if there is an error

    • getParameters

      java.util.Map<java.lang.String,​java.lang.String> getParameters() throws JRDFoxException
      Returns the parameters that the server was created with.
      Returns:
      the parameters of the server
      Throws:
      JRDFoxException - thrown if an error is encountered

    • getVersion

      java.lang.String getVersion() throws JRDFoxException
      Returns the version string of the RDFox instance.
      Returns:
      the version string of the RDFox instance
      Throws:
      JRDFoxException - thrown if an error is encountered

    • getGitSHA

      java.lang.String getGitSHA() throws JRDFoxException
      Returns the string containing the Git SHA identifying the precise version of the RDFox instance code.
      Returns:
      the Git SHA string of the RDFox instance
      Throws:
      JRDFoxException - thrown if an error is encountered

    • getMemoryUse

      long[] getMemoryUse() throws JRDFoxException
      Returns the current memory use of RDFox.
      Returns:
      an array of length two where the element with index 0 contains the maximum allowed memory use, and the element with index 1 contains the currently available memory in bytes
      Throws:
      JRDFoxException - thrown if an error is encountered

    • setMaxMemoryUse

      void setMaxMemoryUse​(long maxUsedBytes) throws JRDFoxException
      Sets the maximum amount of memory that RDFox is allowed to use.
      Parameters:
      maxUsedBytes - the maximum amount of memory in bytes that RDFox is allowed to use
      Throws:
      JRDFoxException - thrown if an error is encountered

    • getNumberOfThreads

      int getNumberOfThreads() throws JRDFoxException
      Returns the number of threads that the server uses for various tasks such as reasoning and data importation.
      Returns:
      the number of threads used by the server
      Throws:
      JRDFoxException - thrown if an error is encountered

    • setNumberOfThreads

      void setNumberOfThreads​(int numberOfThreads) throws JRDFoxException
      Sets the number of threads that the server should use for various tasks such as reasoning and data importation. This operation can be invoked only if no transaction is active.
      Parameters:
      numberOfThreads - the number of threads that the server should use
      Throws:
      JRDFoxException - thrown if an error is encountered

    • getComponentInfo

      ComponentInfo getComponentInfo​(boolean extended) throws JRDFoxException
      Returns diagnostic information about the server as a tree of objects each providing detailed information about the server. Note: This information should be used for diagnostics purposes only. The content of ComponentInfo is subject to change in future version. Callers should not rely on named property or a specific subcomponent being present.
      Parameters:
      extended - if true, the information about all data stores will be returned as well
      Returns:
      information about the server
      Throws:
      JRDFoxException - thrown if an error is encountered

    • listDataStores

      java.util.List<java.lang.String> listDataStores() throws JRDFoxException
      Returns the list of names of data stores available at the connected server.
      Returns:
      the list of names of data stores available at the server
      Throws:
      JRDFoxException - thrown if an error is encountered

    • containsDataStore

      boolean containsDataStore​(java.lang.String dataStoreName) throws JRDFoxException
      Returns true if the connected server contains a data store with the given name.
      Parameters:
      dataStoreName - the name of a data store
      Returns:
      true if the server contains a data store with the name dataStoreName
      Throws:
      JRDFoxException - thrown if an error is encountered

    • createDataStore

      void createDataStore​(java.lang.String dataStoreName, java.util.Map<java.lang.String,​java.lang.String> dataStoreParameters) throws JRDFoxException
      Creates a data store with the given name. The remaining parameters specify the data store type, as well as various data store parameters. The server should not contain a data store with the specified name.
      Parameters:
      dataStoreName - the name of the newly created data store
      dataStoreParameters - the key-value pairs determining various data store parameters (see Data Store Parameters)
      Throws:
      JRDFoxException - thrown if an error is encountered (e.g., if the server already contains a data store with the given name, or if some of the parameters are incorrect)

    • loadDataStoreFromBinaryFormat

      void loadDataStoreFromBinaryFormat​(java.lang.String dataStoreName, java.io.InputStream inputStream) throws JRDFoxException
      Loads a data store with the given name from an input stream containing the store saved in the standard or raw format. The loaded data store will be initialised using the parameters found in the input stream. The server should not contain a data store with the specified name.
      Parameters:
      dataStoreName - the name of the newly created data store
      inputStream - contains the data store encoded using the standard or the raw format
      Throws:
      JRDFoxException - thrown if an error is encountered (e.g., if the server already contains a data store with the given name, or if the format is incorrect)

    • loadDataStoreFromBinaryFormat

      void loadDataStoreFromBinaryFormat​(java.lang.String dataStoreName, java.io.File file) throws JRDFoxException
      Loads a data store with the given name from a file containing the store saved in the standard or raw format. The loaded data store will be initialised using the parameters found in the file. The server should not contain a data store with the specified name.
      Parameters:
      dataStoreName - the name of the newly created data store
      file - contains the data store encoded using the standard or the raw format
      Throws:
      JRDFoxException - thrown if an error is encountered (e.g., if the server already contains a data store with the given name, or if the format is incorrect)

    • loadDataStoreFromBinaryFormat

      void loadDataStoreFromBinaryFormat​(java.lang.String dataStoreName, java.io.InputStream inputStream, java.util.Map<java.lang.String,​java.lang.String> dataStoreParameters) throws JRDFoxException
      Loads a data store with the given name from an input stream containing the store saved in the standard or raw format. The loaded data store will be initialised using the specified parameters, which are the same as in the createDataStore(java.lang.String, java.util.Map<java.lang.String, java.lang.String>) method. Please note that, if the input contains a data store in the raw format, the parameters must be exactly the same as in the input. In contrast, if the input contains a data store in the standard format, most parameters (apart from the equality mode) can be overridden; hence, this method can be used to transfer the data from one data store to another. The server should not contain a data store with the specified name.
      Parameters:
      dataStoreName - the name of the newly created data store
      inputStream - contains the data store encoded using the standard or the raw format
      dataStoreParameters - the key-value pairs determining various data store parameters (see Data Store Parameters)
      Throws:
      JRDFoxException - thrown if an error is encountered (e.g., if the server already contains a data store with the given name, or if the file format is incorrect)

    • loadDataStoreFromBinaryFormat

      void loadDataStoreFromBinaryFormat​(java.lang.String dataStoreName, java.io.File file, java.util.Map<java.lang.String,​java.lang.String> dataStoreParameters) throws JRDFoxException
      Loads a data store with the given name from a file containing the store saved in the standard or raw format. The loaded data store will be initialised using the specified parameters, which are the same as in the createDataStore(java.lang.String, java.util.Map<java.lang.String, java.lang.String>) method. Please note that, if the input contains a data store in the raw format, the parameters must be exactly the same as in the input. In contrast, if the input contains a data store in the standard format, most parameters (apart from the equality mode) can be overridden; hence, this method can be used to transfer the data from one data store to another. The server should not contain a data store with the specified name.
      Parameters:
      dataStoreName - the name of the newly created data store
      file - contains the data store encoded using the standard or the raw format
      dataStoreParameters - the key-value pairs determining various data store parameters (see Data Store Parameters)
      Throws:
      JRDFoxException - thrown if an error is encountered (e.g., if the server already contains a data store with the given name, or if the file format is incorrect)

    • saveDataStoreToBinaryFormat

      void saveDataStoreToBinaryFormat​(java.lang.String dataStoreName, java.io.OutputStream outputStream, BinaryDataStoreFormat format) throws JRDFoxException
      Saves a data store into the specified binary format. This operation can be invoked only if no transaction is active.
      Parameters:
      dataStoreName - the name of the data store to save
      outputStream - receives the binary content of the data store
      format - specifies the format in which the store is saved
      Throws:
      JRDFoxException - thrown if an error is encountered

    • saveDataStoreToBinaryFormat

      void saveDataStoreToBinaryFormat​(java.lang.String dataStoreName, java.lang.String expectedDataStoreUniqueID, long expectedDataStoreVersion, java.io.OutputStream outputStream, BinaryDataStoreFormat format) throws JRDFoxException
      Saves a data store into the specified binary format if the data store's unique ID and version match the expected values. This operation can be invoked only if no transaction is active.
      Parameters:
      dataStoreName - the name of the data store to save
      expectedDataStoreUniqueID - the expected unique ID of the data store
      expectedDataStoreVersion - the expected version of the data store
      outputStream - receives the binary content of the data store
      format - specifies the format in which the store is saved
      Throws:
      JRDFoxException - thrown if an error is encountered

    • saveDataStoreToBinaryFormat

      void saveDataStoreToBinaryFormat​(java.lang.String dataStoreName, java.io.File file, BinaryDataStoreFormat format) throws JRDFoxException
      Saves a data store into the specified binary format. This operation can be invoked only if no transaction is active.
      Parameters:
      dataStoreName - the name of the data store to save
      file - receives the binary content of the data store
      format - specifies the format in which the store is saved
      Throws:
      JRDFoxException - thrown if an error is encountered

    • saveDataStoreToBinaryFormat

      void saveDataStoreToBinaryFormat​(java.lang.String dataStoreName, java.lang.String expectedDataStoreUniqueID, long expectedDataStoreVersion, java.io.File file, BinaryDataStoreFormat format) throws JRDFoxException
      Saves a data store into the specified binary format if the data store's unique ID and version match the expected values. This operation can be invoked only if no transaction is active.
      Parameters:
      dataStoreName - the name of the data store to save
      expectedDataStoreUniqueID - the expected unique ID of the data store
      expectedDataStoreVersion - the expected version of the data store
      file - receives the binary content of the data store
      format - specifies the format in which the store is saved
      Throws:
      JRDFoxException - thrown if an error is encountered

    • deleteDataStore

      void deleteDataStore​(java.lang.String dataStoreName) throws JRDFoxException
      Deletes a data store with the given name from the server. A data store can be deleted only if no connections are open to it.
      Parameters:
      dataStoreName - the name of the data store to delete
      Throws:
      JRDFoxException - thrown if an error is encountered (e.g., if the server does not contain a data store with the given name)

    • deleteDataStore

      void deleteDataStore​(java.lang.String dataStoreName, java.lang.String expectedDataStoreUniqueID, long expectedDataStoreVersion) throws JRDFoxException
      Deletes a data store with the given name from the server if the data store's unique ID and version match the expected values. A data store can be deleted only if no connections are open to it.
      Parameters:
      dataStoreName - the name of the data store to delete
      expectedDataStoreUniqueID - the expected unique ID of the data store
      expectedDataStoreVersion - the expected version of the data store
      Throws:
      JRDFoxException - thrown if an error is encountered (e.g., if the server does not contain a data store with the given name)

    • newDataStoreConnection

      DataStoreConnection newDataStoreConnection​(java.lang.String dataStoreName) throws JRDFoxException
      Creates a connection to the data store of this server with the given name. The new data store connection uses the same credentials as this server connection.
      Parameters:
      dataStoreName - the name of the data store to connect to
      Returns:
      a connection to the specified data store
      Throws:
      JRDFoxException - thrown if an error is encountered (e.g., if the server does not contain a data store with the given name)

    • listRoles

      java.util.List<java.lang.String> listRoles() throws JRDFoxException
      Returns the list of all roles available at the server.
      Returns:
      the list of all roles available at the server.
      Throws:
      JRDFoxException - thrown if there is an error

    • createRole

      void createRole​(java.lang.String roleName, java.lang.String password) throws JRDFoxException
      Creates a new role with the given name and password.
      Parameters:
      roleName - the new role name
      password - the password of the new role
      Throws:
      JRDFoxException - thrown if there is an error

    • createRole

      void createRole​(java.lang.String roleName, java.lang.String passwordOrHash, boolean isHash) throws JRDFoxException
      Creates a new role with the given name and password.
      Parameters:
      roleName - the new role name
      passwordOrHash - the password or its hash of the new role
      isHash - if true, then passwordOrHash is interpreted as the hash of the password; otherwise, passwordOrHash is interpreted as the verbatim password
      Throws:
      JRDFoxException - thrown if there is an error

    • deleteRole

      void deleteRole​(java.lang.String roleName) throws JRDFoxException
      Deletes a role with the given name.
      Parameters:
      roleName - the name of the role to delete
      Throws:
      JRDFoxException - thrown if there is an error

    • changeRolePassword

      void changeRolePassword​(java.lang.String currentPassword, java.lang.String newPassword) throws JRDFoxException
      Creates the password of the role that is associated with this connection. The change is performed only if the current password matches.
      Parameters:
      currentPassword - the current password of the role associated with this connection
      newPassword - the new password for the role associated with this connection
      Throws:
      JRDFoxException - thrown if there is an error

    • getRolePasswordHash

      java.lang.String getRolePasswordHash​(java.lang.String roleName) throws JRDFoxException
      Returns the password hash for the given role name.
      Parameters:
      roleName - the name of the role for which the password hash should be returned
      Returns:
      the password hash
      Throws:
      JRDFoxException - thrown if there is an error

    • listRoleMemberships

      java.util.List<java.lang.String> listRoleMemberships​(java.lang.String roleName) throws JRDFoxException
      Lists the roles that the given role is a member of.
      Parameters:
      roleName - the name of the role for which the memberships should be returned
      Returns:
      the list of roles that the given role is a member of
      Throws:
      JRDFoxException - thrown if there is an error

    • listRoleMembers

      java.util.List<java.lang.String> listRoleMembers​(java.lang.String roleName) throws JRDFoxException
      Lists the roles that are members of the given role.
      Parameters:
      roleName - the name of the role for which the members should be returned
      Returns:
      the list of roles that are members of the given role
      Throws:
      JRDFoxException - thrown if there is an error

    • isMemberOf

      boolean isMemberOf​(java.lang.String roleName, java.lang.String superRoleName) throws JRDFoxException
      Checks whether the given role is a member of another super-role.
      Parameters:
      roleName - the name of the role for which the check is performed
      superRoleName - the name of the potential super-role for which the check is performed
      Returns:
      true if the given role is a member of another super-role.
      Throws:
      JRDFoxException - thrown if there is an error

    • grantRole

      boolean grantRole​(java.lang.String roleName, java.lang.String superRoleName) throws JRDFoxException
      Grants the membership of a role in another role.
      Parameters:
      roleName - the name of the role that is to be made member of superRoleName
      superRoleName - the name of the role that should get roleName as member
      Returns:
      true if the role was granted, false if it was already held
      Throws:
      JRDFoxException - thrown if there is an error

    • revokeRole

      boolean revokeRole​(java.lang.String roleName, java.lang.String superRoleName) throws JRDFoxException
      Revokes the membership of a role in another role.
      Parameters:
      roleName - the name of the role that should stop being member of superRoleName
      superRoleName - the name of the role that for which roleName should stop being a member
      Returns:
      true if the role was revoked, false if it was not held in the first place
      Throws:
      JRDFoxException - thrown if there is an error

    • listPrivileges

      java.util.Map<java.lang.String,​java.lang.Byte> listPrivileges​(java.lang.String roleName) throws JRDFoxException
      Lists the privileges of a given role. The result is a map of resource specifiers to the access types that the role currently has.
      Parameters:
      roleName - the name of the role whose privileges are being listed
      Returns:
      the map of resource specifiers to the access types (specified as a bit-mask of ACCESS_TYPE_* values)
      Throws:
      JRDFoxException - thrown if there is an error

    • grantPrivileges

      boolean grantPrivileges​(java.lang.String roleName, java.lang.String resourceSpecifier, byte accessTypesToGrant) throws JRDFoxException
      Grants privileges over a resource specifier to a role.
      Parameters:
      roleName - the name of the role to which the privileges are being granted
      resourceSpecifier - identifies a resource to which the privileges are being granted
      accessTypesToGrant - the access types (specified as a bit-mask of ACCESS_TYPE_* values) that are to be granted
      Returns:
      true if the privileges were granted, false if they were already held
      Throws:
      JRDFoxException - thrown if there is an error

    • revokePrivileges

      boolean revokePrivileges​(java.lang.String roleName, java.lang.String resourceSpecifier, byte accessTypesToRevoke) throws JRDFoxException
      Revokes privileges over a resource specifier from a role.
      Parameters:
      roleName - the name of the role to which the privileges are being granted
      resourceSpecifier - identifies a resource to which the privileges are being granted
      accessTypesToRevoke - the access types (specified as a bit-mask of ACCESS_TYPE_* values) that are to be revoked
      Returns:
      true if the privileges were revoked, false if they weren't held in the first place
      Throws:
      JRDFoxException - thrown if there is an error