Package com.franz.agraph.repository

Class AGServer

java.lang.Object
com.franz.agraph.repository.AGServer
All Implemented Interfaces:
Closeable, AutoCloseable
public class AGServer extends Object implements Closeable
The starting point for interacting with an AllegroGraph server.

An AGServer references AGCatalogs, which reference AGRepositories, from which connections may be obtained, on which data is manipulated and queried.

AGServer provides methods for User (and Role) Management.

AGServer also provides federated repositories.

  • Field Details

    • DEFAULT_HTTP_PORT

      public static final int DEFAULT_HTTP_PORT
      Default AG server port for HTTP connections.
      See Also:

    • DEFAULT_HTTPS_PORT

      public static final int DEFAULT_HTTPS_PORT
      Default AG server port for HTTPS connections.
      See Also:

  • Constructor Details

    • AGServer

      public AGServer(String serverURL, String username, String password)
      Creates an instance for interacting with an AllegroGraph server.

      Uses Basic authentication.

      Parameters:
      serverURL - the URL of the server (trailing slashes are removed)
      username - a user id for authenticating with the server
      password - a password for authenticating with the server
      See Also:

    • AGServer

      public AGServer(String username, String password, AGHTTPClient httpClient)
      Creates an instance for interacting with an AllegroGraph server.

      Uses Basic authentication with the server as configured in the httpClient instance.

      Parameters:
      username - a user id for authenticating with the server
      password - a password for authenticating with the server
      httpClient - the AGHTTPClient instance to use

    • AGServer

      public AGServer(AGHTTPClient httpClient)
      Creates an instance for interacting with an AllegroGraph server.

      Attempts X.509 server and client authentication when no username and password have been set in the httpClient, and properties such as

      
 javax.net.ssl.keyStore,
 javax.net.ssl.keyStorePassword,
 javax.net.ssl.keyStoreType, and
 javax.net.ssl.trustStore

      have been set appropriately.

      Also set SSL directives in the server's config file, e.g:

      
 SSLPort 10036
 SSLClientAuthRequired true
 SSLClientAuthUsernameField CN
 SSLCertificate /path/agraph.cert
 SSLCAFile /path/ca.cert
      For more details, see Server configuration.
      Parameters:
      httpClient - the AGHTTPClient instance to use
      See Also:

    • AGServer

      public AGServer(String serverURL)
      Creates an instance for interacting with an AllegroGraph server.

      Uses a new default AGHTTPClient instance having the given serverURL.

      Attempts X.509 server and client authentication when properties such as

      
 javax.net.ssl.keyStore,
 javax.net.ssl.keyStorePassword,
 javax.net.ssl.keyStoreType, and
 javax.net.ssl.trustStore

      have been set appropriately.

      Also set SSL directives in the server's config file, e.g:

      
 SSLPort 10036
 SSLClientAuthRequired true
 SSLClientAuthUsernameField CN
 SSLCertificate /path/agraph.cert
 SSLCAFile /path/ca.cert

      For more details, see Server configuration.

      Parameters:
      serverURL - the URL of the server (trailing slashes are removed)
      See Also:

  • Method Details

    • createRepository

      public static AGRepository createRepository(String repoName, String catalogName, String serverURL, String username, String password) throws RepositoryException
      Creates or opens a repository in the specified catalog.
      Parameters:
      repoName - name of the repository to create
      catalogName - name of the catalog where repoName will be created
      serverURL - URL at which the AG server is found
      username - name of the authenticating user, or null
      password - password (plaintext) of the authenticating user, or null
      Returns:
      an initialized AGRepository instance for the newly created repository
      Throws:
      RepositoryException - if there is an error with this request

    • createRepositoryConnection

      public static AGRepositoryConnection createRepositoryConnection(String repoName, String catalogName, String serverURL, String username, String password) throws RepositoryException
      Creates or opens a repository in the specified catalog.
      Parameters:
      repoName - name of the repository to create
      catalogName - name of the catalog where repoName will be created
      serverURL - URL at which the AG server is found
      username - name of the authenticating user, or null
      password - password (plaintext) of the authenticating user, or null
      Returns:
      a connection to the newly created and initialized repository
      Throws:
      RepositoryException - if there is an error with this request.

    • getServerURL

      public String getServerURL()
      Returns the URL of this AllegroGraph server.
      Returns:
      the URL of this AllegroGraph server

    • getUser

      public String getUser()

    • getPassword

      public String getPassword()

    • getHTTPClient

      public AGHTTPClient getHTTPClient()
      Returns the AGHTTPClient instance for this server.
      Returns:
      the AGHTTPClient instance for this server

    • getVersion

      public String getVersion() throws AGHttpException
      Returns:
      the server version
      Throws:
      AGHttpException - if there is an error with this request

    • getComparableVersion

      public AGServerVersion getComparableVersion() throws AGHttpException
      Returns:
      the server version as comparable AGServerVersion object.
      Throws:
      AGHttpException - if there is no cachedServerVersion and there was an error with getVersion() request.

    • getBuildDate

      public String getBuildDate() throws AGHttpException
      Returns:
      the server's build date
      Throws:
      AGHttpException - if there is an error with this request

    • getRevision

      public String getRevision() throws AGHttpException
      Returns:
      the server's revision info
      Throws:
      AGHttpException - if there is an error with this request

    • getRootCatalog

      public AGCatalog getRootCatalog()
      Returns the unnamed root catalog for this AllegroGraph server. Note: this method may be deprecated in an upcoming release.
      Returns:
      the root catalog
      See Also:

    • listCatalogs

      public List<String> listCatalogs() throws AGHttpException
      Returns a List of catalog ids known to this AllegroGraph server.
      Returns:
      List of catalog ids
      Throws:
      AGHttpException - if there is an error with this request

    • getCatalog

      public AGCatalog getCatalog(String catalogID) throws AGHttpException
      Gets the catalog instance for a given catalog id.

      Returns the root catalog if the id is a root id. If the catalog Id is not found on the server, returns null.

      Parameters:
      catalogID - a catalog id
      Returns:
      the corresponding catalog instance
      Throws:
      AGHttpException - if there is an error with this request

    • getCatalog

      public AGCatalog getCatalog()
      Returns the unnamed root catalog for this AllegroGraph server.
      Returns:
      the root catalog

    • createCatalog

      public AGCatalog createCatalog(String catalogID) throws AGHttpException
      Returns an AGCatalog instance for the given catalogID.

      If the catalog already exists on the server, an AGCatalog instance is simply returned. If the catalog does not exist, it is created if the server has been configured to allow dynamic catalogs; otherwise, an exception is thrown.

      Parameters:
      catalogID - the id (the name) of the catalog
      Returns:
      an AGCatalog instance
      Throws:
      AGHttpException - if there is an error with this request

    • deleteCatalog

      public void deleteCatalog(String catalogID) throws AGHttpException
      Deletes any catalog with the given repository id.

      This method only applies to dynamically created catalogs.

      Parameters:
      catalogID - the name of the catalog to delete
      Throws:
      AGHttpException - if there is an error with this request

    • virtualRepository

      public AGVirtualRepository virtualRepository(String storeSpec)
      Creates a virtual repository with the given store specification.

      The storeSpec parameter is a string using the minilanguage for store specification described in the HTTP protocol document (see the store parameter there).

      This syntax can be used to create federations, graph-filtered stores, reasoning stores, and compositions thereof.

      Parameters:
      storeSpec - the store specification
      Returns:
      a virtual repository based on storeSpec

    • federate

      public AGVirtualRepository federate(AGAbstractRepository... repositories)
      Creates a federated view of multiple repositories.

      See Managing Massive Data - Federation.

      Parameters:
      repositories - repositories that will compose the virtual repository
      Returns:
      a virtual repository that federates queries across multiple physical repositories

    • close

      public void close()
      Close the HTTP connection resources to the AllegroGraph server.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • listUsers

      public List<String> listUsers() throws AGHttpException
      Returns a List of user ids known to this AllegroGraph server.
      Returns:
      List of user ids
      Throws:
      AGHttpException - if there is an error with this request

    • addUser

      public void addUser(String user, String password) throws AGHttpException
      Adds a user to the server.
      Parameters:
      user - user id to add
      password - user's password
      Throws:
      AGHttpException - if there is an error with this request

    • deleteUser

      public void deleteUser(String user) throws AGHttpException
      Deletes a user from the server.
      Parameters:
      user - user id to delete
      Throws:
      AGHttpException - if there is an error with this request

    • addUserAccess

      public void addUserAccess(String user, boolean read, boolean write, String catalog, String repository) throws AGHttpException
      Adds to a user's access list for this server.

      Access is documented here.

      Parameters:
      user - user id
      read - read access
      write - write access
      catalog - catalog id, or "*" (or null) for all catalogs
      repository - repository id, or "*" (or null) for all repos, in the given catalog(s)
      Throws:
      AGHttpException - if there is an error with this request

    • deleteUserAccess

      public void deleteUserAccess(String user, boolean read, boolean write, String catalog, String repository) throws AGHttpException
      Deletes from a user's access list for this server.

      Access is documented here.

      Parameters:
      user - user id
      read - read access
      write - write access
      catalog - catalog id, or "*" (or null) for all catalogs
      repository - repository id, or "*" (or null) for all repos, in the given catalog(s)
      Throws:
      AGHttpException - if there is an error with this request

    • listUserAccess

      public org.json.JSONArray listUserAccess(String user) throws AGHttpException
      Returns a user's access list for this server.

      Access is documented here.

      Parameters:
      user - user id
      Returns:
      a JSONArray describing user's access list
      Throws:
      AGHttpException - if there is an error with this request

    • addUserSecurityFilter

      public void addUserSecurityFilter(String user, String type, String s, String p, String o, String g) throws AGHttpException
      Adds a security filter for a user.
      Parameters:
      user - user id
      type - filter type is "allow" or "disallow"
      s - subject to allow/disallow, in NTriples format
      p - predicate to allow/disallow, in NTriples format
      o - object to allow/disallow, in NTriples format
      g - graph to allow/disallow, in NTriples format
      Throws:
      AGHttpException - if there is an error with this request

    • deleteUserSecurityFilter

      public void deleteUserSecurityFilter(String user, String type, String s, String p, String o, String g) throws AGHttpException
      Deletes a security filter for a user.
      Parameters:
      user - user id
      type - filter type is "allow" or "disallow"
      s - subject to allow/disallow, in NTriples format
      p - predicate to allow/disallow, in NTriples format
      o - object to allow/disallow, in NTriples format
      g - graph to allow/disallow, in NTriples format
      Throws:
      AGHttpException - if there is an error with this request

    • listUserSecurityFilters

      public org.json.JSONArray listUserSecurityFilters(String user, String type) throws AGHttpException
      Returns a list of security filters of the given type for a user
      Parameters:
      user - user id
      type - filter type is "allow" or "disallow"
      Returns:
      a JSONArray of user's security filters
      Throws:
      AGHttpException - if there is an error with this request

    • changeUserPassword

      public void changeUserPassword(String user, String password) throws AGHttpException
      Change the password for USER to PASSWORD
      Parameters:
      user - user id
      password - the new password to require for user
      Throws:
      AGHttpException - if there is an error with this request

    • listUserEffectiveAccess

      public org.json.JSONArray listUserEffectiveAccess(String user) throws AGHttpException
      Returns a user's effective access list for this server.

      Includes the access granted to roles that this user has.

      Parameters:
      user - user id
      Returns:
      a JSONArray describing user's effective access
      Throws:
      AGHttpException - if there is an error with this request

    • listUserPermissions

      public List<String> listUserPermissions(String user) throws AGHttpException
      Returns a list of permissions for a user.

      Permissions are documented here.

      Parameters:
      user - user id
      Returns:
      list of permissions
      Throws:
      AGHttpException - if there is an error with this request

    • listUserEffectivePermissions

      public List<String> listUserEffectivePermissions(String user) throws AGHttpException
      Returns a list of effective permissions for a user.

      Includes the permission granted to roles that this user has.

      Permissions are documented here.

      Parameters:
      user - user id
      Returns:
      list of permissions
      Throws:
      AGHttpException - if there is an error with this request

    • addUserPermission

      public void addUserPermission(String user, String permission) throws AGHttpException
      Adds to a user's permission list.
      Parameters:
      user - user id
      permission - "super" or "eval" or "session"
      Throws:
      AGHttpException - if there is an error with this request

    • deleteUserPermission

      public void deleteUserPermission(String user, String permission) throws AGHttpException
      Deletes from a user's permission list.
      Parameters:
      user - user id
      permission - "super" or "eval" or "session"
      Throws:
      AGHttpException - if there is an error with this request

    • listRoles

      public List<String> listRoles() throws AGHttpException
      Returns a list of roles known to this server.
      Returns:
      a list of roles
      Throws:
      AGHttpException - if there is an error with this request

    • addRole

      public void addRole(String role) throws AGHttpException
      Adds a role to this server.
      Parameters:
      role - role id
      Throws:
      AGHttpException - if there is an error with this request

    • addRoleAccess

      public void addRoleAccess(String role, boolean read, boolean write, String catalog, String repository) throws AGHttpException
      Adds to a role's access list for this server.

      Access is documented here.

      Parameters:
      role - role id
      read - read access
      write - write access
      catalog - catalog id, or "*" (or null) for all catalogs
      repository - repository id, or "*" (or null) for all repos, in the given catalog(s)
      Throws:
      AGHttpException - if there is an error with this request

    • listRoleAccess

      public org.json.JSONArray listRoleAccess(String role) throws AGHttpException
      Returns a role's access list for this server.

      Access is documented here.

      Parameters:
      role - role id
      Returns:
      the access list for the specified role
      Throws:
      AGHttpException - if there is an error with this request

    • addRoleSecurityFilter

      public void addRoleSecurityFilter(String role, String type, String s, String p, String o, String g) throws AGHttpException
      Adds a security filter for a role.
      Parameters:
      role - role id
      type - filter type is "allow" or "disallow"
      s - subject to allow/disallow, in NTriples format
      p - predicate to allow/disallow, in NTriples format
      o - object to allow/disallow, in NTriples format
      g - graph to allow/disallow, in NTriples format
      Throws:
      AGHttpException - if there is an error with this request

    • listRoleSecurityFilters

      public org.json.JSONArray listRoleSecurityFilters(String role, String type) throws AGHttpException
      Returns a list of security filters of the given type for a role
      Parameters:
      role - role id
      type - filter type is "allow" or "disallow"
      Returns:
      the security filters for the role
      Throws:
      AGHttpException - if there is an error with this request

    • deleteRoleSecurityFilter

      public void deleteRoleSecurityFilter(String role, String type, String s, String p, String o, String g) throws AGHttpException
      Deletes a security filter for a role.
      Parameters:
      role - role id
      type - filter type is "allow" or "disallow"
      s - subject to allow/disallow, in NTriples format
      p - predicate to allow/disallow, in NTriples format
      o - object to allow/disallow, in NTriples format
      g - graph to allow/disallow, in NTriples format
      Throws:
      AGHttpException - if there is an error with this request

    • listUserRoles

      public List<String> listUserRoles(String user) throws AGHttpException
      Returns a list of roles for a user.
      Parameters:
      user - the user to lookup
      Returns:
      a list of roles
      Throws:
      AGHttpException - if there is an error with this request

    • addUserRole

      public void addUserRole(String user, String role) throws AGHttpException
      Adds a role for this user.
      Parameters:
      user - user id
      role - role id
      Throws:
      AGHttpException - if there is an error with this request

    • deleteUserRole

      public void deleteUserRole(String user, String role) throws AGHttpException
      Deletes a role for this user.
      Parameters:
      user - user id
      role - role id
      Throws:
      AGHttpException - if there is an error with this request

    • deleteRoleAccess

      public void deleteRoleAccess(String role, boolean read, boolean write, String catalog, String repository) throws AGHttpException
      Deletes from a role's access list for this server.
      Parameters:
      role - role id
      read - read access
      write - write access
      catalog - catalog id, or "*" (or null) for all catalogs
      repository - repository id, or "*" (or null) for all repos, in the given catalog(s)
      Throws:
      AGHttpException - if there is an error with this request

    • deleteRole

      public void deleteRole(String role) throws AGHttpException
      Deletes a role from this server.
      Parameters:
      role - role id
      Throws:
      AGHttpException - if there is an error with this request

    • addRolePermission

      public void addRolePermission(String role, String permission) throws AGHttpException
      Adds to a role's permission list.
      Parameters:
      role - role id
      permission - "super" or "eval" or "session"
      Throws:
      AGHttpException - if there is an error with this request

    • deleteRolePermission

      public void deleteRolePermission(String role, String permission) throws AGHttpException
      Delete from a role's permission list.
      Parameters:
      role - role id
      permission - "super" or "eval" or "session"
      Throws:
      AGHttpException - if there is an error with this request

    • listRolePermissions

      public List<String> listRolePermissions(String role) throws AGHttpException
      Returns a list of permissions for a role.

      Permissions are documented here.

      Parameters:
      role - role id
      Returns:
      list of permissions
      Throws:
      AGHttpException - if there is an error with this request

    • getExecutor

      public ScheduledExecutorService getExecutor()
      Gets the default executor object that will be used by connections to schedule maintenance operations.
      Returns:
      An executor instance

    • setExecutor

      public void setExecutor(ScheduledExecutorService executor)
      Changes the default executor object that will be used by connections to schedule maintenance operations.
      Parameters:
      executor - An executor instance

    • createRepository

      public AGRepository createRepository(String reponame, AGCatalog catalog, boolean strict) throws RepositoryException
      Creates or opens a repository in the specified catalog.
      Parameters:
      reponame - name of the repository to create
      catalog - AGCatalog instance where the repository will be created
      strict - if true, throw an exception if the repository exists. Otherwise the existing repository will be opened.
      Returns:
      an initialized AGRepository instance for the newly created repository
      Throws:
      RepositoryException - if there is an error with this request

    • createRepository

      public AGRepository createRepository(String reponame, String catname, boolean strict) throws RepositoryException
      Creates or opens a repository in the specified catalog.
      Parameters:
      reponame - name of the repository to create
      catname - name of the catalog in which to create the repository
      strict - if true, throw an exception if the repository exists. Otherwise the existing repository will be opened.
      Returns:
      an initialized AGRepository instance for the newly created repository
      Throws:
      RepositoryException - if there is an error with this request

    • createRepository

      public AGRepository createRepository(String reponame, String catname) throws RepositoryException
      Creates or opens a repository in the specified catalog.
      Parameters:
      reponame - name of the repository to create
      catname - name of the catalog in which to create the repository
      Returns:
      an initialized AGRepository instance for the newly created repository
      Throws:
      RepositoryException - if there is an error with this request

    • createRepository

      public AGRepository createRepository(String reponame) throws RepositoryException
      Creates or opens a repository in the root catalog.
      Parameters:
      reponame - name of the repository to create
      Returns:
      an initialized AGRepository instance for the newly created repository
      Throws:
      RepositoryException - if there is an error with this request

    • createRepositoryConnection

      public AGRepositoryConnection createRepositoryConnection(String reponame, AGCatalog cat, boolean strict) throws RepositoryException
      Creates or opens a repository in the specified catalog.
      Parameters:
      reponame - name of the repository to create
      cat - catalog in which to create the repository
      strict - if true, throw an exception if the repository exists. Otherwise the existing repository will be opened.
      Returns:
      a connection to the newly created and initialized repository
      Throws:
      RepositoryException - if there is an error with this request.

    • createRepositoryConnection

      public AGRepositoryConnection createRepositoryConnection(String reponame, String catname, boolean strict) throws RepositoryException
      Creates or opens a repository in the specified catalog.
      Parameters:
      reponame - name of the repository to create
      catname - name of the catalog in which to create the repository
      strict - if true, throw an exception if the repository exists. Otherwise the existing repository will be opened.
      Returns:
      a connection to the newly created and initialized repository
      Throws:
      RepositoryException - if there is an error with this request.

    • deleteRepository

      public void deleteRepository(String reponame, String catname)
      Deletes a repository.
      Parameters:
      reponame - Repository name.
      catname - Catalog name, null or an empty string maps to the root catalog.

    • getLogFile

      public String getLogFile() throws AGHttpException
      Retrieves the whole log file as a single string.
      Returns:
      the log file.
      Throws:
      AGHttpException - if there is an error with this request

    • readLogFile

      public Reader readLogFile()
      Retrieves the log file as a text stream. Note that it is important to close the returned stream, so the connection can be closed or reused.
      Returns:
      Log file stream. Must be closed by the caller.