Package com.appliedolap.essbase

Interface EssServer

All Known Implementing Classes:
EssServerImpl
public interface EssServer

  • Field Details

    • MAX_APPLICATIONS

      static final int MAX_APPLICATIONS
      For now, we're setting a generous upper limit on the number of applications that can be returned in a listing. We may want to revisit this in the future. This library is currently designed to hide pagination details so that they don't leak into the abstractions provided in this library, but we may need to rethink this in the future.
      See Also:

    • DEFAULT_REST_API_PATH

      static final String DEFAULT_REST_API_PATH
      See Also:

  • Method Details

    • getName

      String getName()

    • getType

      EssObject.Type getType()

    • getApplications

      List<EssApplication> getApplications()
      Fetch the list of applications available on the server for the currently connected user. The number of returned applications is limited to 1000 (the value of MAX_APPLICATIONS).
      Returns:
      a list of applications

    • getApplication

      EssApplicationImpl getApplication(String applicationName)
      Gets an application with the given name
      Parameters:
      applicationName - the application name
      Returns:
      an application object for the application

    • getFiles

      List<EssFile> getFiles()
      Gets the list of files available through the files API. The returned files may include folders.
      Returns:
      the list of files on this server

    • getFile

      EssFile getFile(String path, String filename)
      Gets a file using the specified path and name.
      Parameters:
      path - the path to the file, such as gallery/Applications/Demo Samples/Block Storage
      filename - the name of the file, such as Sample_Basic.xlsx
      Returns:
      the file if it exists, null otherwise

    • getSessions

      List<EssSession> getSessions()

    • getApiSpec

      EssApiSpec getApiSpec()
      The server's own OpenAPI/Swagger definition of its REST API.

      Where it lives depends on the release, which is the reason this exists rather than callers building the URL themselves: 21.7 serves a Swagger 2.0 document at /rest/v1/swagger.json and answers 404 for openapi.json, while 26.1 serves an OpenAPI 3.0.1 document at /rest/v1/openapi.json and answers 404 for swagger.json. Asking for the wrong one is not a soft failure - it is a 404 - so the candidates are tried in turn.

      Throws:
      EssApiException - if no known location answered

    • getInstanceDetails

      Map<String,Object> getInstanceDetails()
      Everything the server reports about this deployment, exactly as it reports it.

      Deliberately untyped, unlike getAboutInstance(). This endpoint is a bag of capability flags describing one deployment, and which flags exist varies by version: 21.7 answers with idcs and provisioningSupported, while 26.1 answers with ten fields including a split of that one into service- and application-role provisioning, several AI feature flags, and a logout URL. A generated model pins the field names at whatever the spec said when it was generated and silently discards the rest, so against a newer server the typed view goes empty precisely when the server has more to say. A map cannot go out of date that way.

      Values are left as the server sent them - booleans stay booleans - so a caller can test a flag as well as display it. idcs is the interesting one: it says the deployment authenticates through Oracle's identity service, which is what makes a username and password useless for a federated user.

      Returns:
      the fields the server returned, in the order it returned them

    • getAboutDetails

      Map<String,Object> getAboutDetails()
      Everything the server reports about the product, exactly as it reports it.

      Untyped for the same reason getInstanceDetails() is: getAbout() names four fields fixed at whatever the spec said when the client was generated, and a 26.1 server answers with five - it adds listingVersion, which a typed view drops on the floor without saying so. The fields here are whatever came back.

      Returns:
      the fields the server returned, in the order it returned them

    • getAuthentication

      EssAuthentication getAuthentication()
      How this connection authenticates, so that code outside the generated client can present the same identity - a download bypass, or a local proxy standing in front of the server's own web pages.

      Returns the live strategy rather than a snapshot: ask it for headers at the moment of the request, because a session-based strategy's answer changes once a session is established, and again once it is signed off.

    • signOff

      void signOff()
      Ends this client's own session on the server.

      Distinct from killSessions(boolean), which ends other people's. This is signing off: the session this client established stops being valid, and the server stops holding it.

      What happens next depends on how this connection authenticates. With a username and password, the next call simply authenticates again and gets a fresh session. With a session supplied from outside - a federated sign-in, say - there is nothing to fall back to and subsequent calls will be rejected, which is precisely what signing off means in that case.

    • getSessionExpiry

      Optional<Instant> getSessionExpiry()
      When this client's session expires, if the server has said. Empty when there is no session, or when the session was supplied from outside rather than established here - the expiry is reported alongside the session, so only the client that established it hears about it.

    • killSessions

      void killSessions(boolean logoff)
      Kill all sessions on the server.
      Parameters:
      logoff - true to also log them off

    • killSessions

      void killSessions(String userId, boolean logoff)
      Kill all sessions on the server for the given user.
      Parameters:
      userId - the user ID
      logoff - true to also log them off

    • getHomePath

      EssFolder getHomePath()
      Gets the home path of the currently connected user. The value of the home path is returned by a REST API call (curiously, one that returns plaintext instead of JSON but whatever). The value is ostensibly /users/ followed by the name of the connected user (e.g. /users/admin).
      Returns:
      a folder object for the user's home path

    • getSharedPath

      EssFolder getSharedPath()
      The shared folder every user can see, /shared.

      The counterpart to getHomePath(), which was here without it.

      Returns:
      the shared folder

    • getUploadConfig

      EssUploadConfig getUploadConfig()
      How this server wants large files uploaded - the part size, and how many parts it allows.

      Rarely needed directly: EssFolder.uploadFile(java.io.File) already reads this and sends a file whichever way the server asks for. Worth having for anything that wants to say in advance what an upload is going to involve.

      Returns:
      the upload configuration

    • getUtilities

      List<EssUtility> getUtilities()
      Gets the list of utilities on this server.
      Returns:
      the server utilities

    • getJobs

      List<EssJob> getJobs()
      Gets the list of jobs on this server.
      Returns:
      the list of jobs

    • getGroups

      List<EssGroup> getGroups()
      Gets a list of groups on this server
      Returns:
      the list of groups

    • createGroup

      EssGroup createGroup(String name, String description, String role)
      Creates a group.

      Only on a server that owns its own security; a deployment behind an external identity provider keeps its groups in the provider and refuses this, the same as it refuses getGroups().

      Parameters:
      name - the group name, which is also its id
      description - what the group is for, or null
      role - the service-level role it grants its members - User, Power User or Service Administrator. Required: the server rejects a group without one.
      Returns:
      the group as the server created it

    • getGroup

      EssGroup getGroup(String name)
      One group by name.
      Parameters:
      name - the group name
      Returns:
      the group
      Throws:
      NoSuchEssbaseObjectException - if there is no such group

    • getUsers

      List<EssUser> getUsers()
      The users this server holds.

      Only meaningful where Essbase owns its own security. A deployment behind an external identity provider - idcs in getInstanceDetails() - keeps its users in the provider and answers HTTP 400 "This operation is not supported. Contact administrator" here, the same as it does for getGroups(). Check the flag before asking, rather than treating the refusal as a failure.

      Returns:
      the users, where the server has any to report

    • getPermissions

      List<EssPermission> getPermissions()
      Who holds which service-level role - Service Administrator, Power User, User.

      Unlike getUsers() and getGroups(), this answers on a deployment behind an external identity provider: the directory lives there, but the role assignments are Essbase's own. It is the one way to see who can do what on such a server.

      Returns:
      the service role assignments

    • getVariables

      List<EssServerVariable> getVariables()
      Gets server-scoped variables.
      Returns:
      the server-wide variables

    • createVariable

      EssServerVariable createVariable(String name, String value)
      Creates a new server-wide variable with the given name and value.
      Parameters:
      name - the name of the variable
      value - the value of the variable

    • getAbout

      EssServerImpl.About getAbout()
      Gets the "about" information for this server.
      Returns:
      the server about info

    • getAboutInstance

      EssServerImpl.AboutInstance getAboutInstance()

    • createApplication

      void createApplication(String applicationName, String databaseName)
      Creates an application (and a database) with the given names. While we tend to historically think of Essbase as employing the concept of an application containing one or more databases/cubes, most of the operations in the REST API are centered around actions you do on a particular cube, and in cases like these where you are creating a cube, there is no separate application creation step, it just gets created or re-used as the case may be.

      The default database creation options will be BSO cube with scenarios and duplicates turned off. For more granular control of the created database type, use createApplication(String, String, EssServerImpl.DatabaseCreateOptions).

      Parameters:
      applicationName - the application name
      databaseName - the database name

    • createApplication

      void createApplication(String applicationName, String databaseName, EssServerImpl.DatabaseCreateOptions databaseCreateOptions)
      Create an application/database with the given name and options.
      Parameters:
      applicationName - the name of the application
      databaseName - the name of the database/cube
      databaseCreateOptions - the database creation options

    • createApplicationFromWorkbook

      EssJob createApplicationFromWorkbook(String application, String database, EssFile file)
      Creates or updates an application from an uploaded workbook.
      Parameters:
      application - the application
      database - the cube/database
      file - the XLSX file
      Returns:
      a new job for the creation process

    • createApplicationFromWorkbook

      EssJob createApplicationFromWorkbook(String application, String database, EssFile file, EssWorkbookImportOptions options)
      Builds or updates an application from a workbook, choosing what the import should do.

      Worth choosing rather than accepting: a workbook usually carries data and scripts as well as an outline, and importing only the outline leaves a cube whose every upper level reads #Missing. See EssWorkbookImportOptions, whose defaults load and calculate.

      Parameters:
      application - the application to build
      database - the cube within it
      file - the workbook, in the server's catalogue
      options - what the import should do
      Returns:
      the submitted job, which runs in the background

    • getURLs

      List<EssURL> getURLs()
      Returns the list of URLs known to this server. Generally speaking this seems to be the URL for the Jet UI, REST API, XMLA provider, and some others.
      Returns:
      list of URLs from the corresponding API

    • getConnections

      List<EssConnection> getConnections()
      The global connections defined on this server.
      Returns:
      the connections

    • getConnection

      Optional<EssConnection> getConnection(String name)
      One connection by name.
      Parameters:
      name - the connection name
      Returns:
      the connection, or empty if there is none

    • createFileConnection

      EssConnection createFileConnection(String name, String catalogPath, String description)
      Creates a connection to a file in the Essbase catalogue.

      The path names a file, not the folder holding it - a file connection stands for one file, and the data source built on it carries no filename of its own.

      Parameters:
      name - the connection name
      catalogPath - the file, e.g. /gallery/Technical/Filters/UserDetails.csv
      description - optional description
      Returns:
      the connection as created

    • testFileConnection

      Optional<String> testFileConnection(String name, String catalogPath)
      Tests a connection that hasn't been saved, so a caller can check before committing.
      Parameters:
      name - the connection name to test under
      catalogPath - the file to point at
      Returns:
      empty when it connects, otherwise the server's reason

    • deleteDataSource

      void deleteDataSource(String name)
      Removes a global data source.
      Parameters:
      name - the data source name

    • getDataSources

      List<EssDataSource> getDataSources()

    • getDataSource

      EssDataSource getDataSource(String dataSourceName)
      Get the data source with the given name. Will throw NoSuchEssbaseObjectException if there is no data source with that name.
      Parameters:
      dataSourceName - the data source name
      Returns:
      the data source with that name

    • streamDataSource

      void streamDataSource(String query, boolean includeHeaders, String delimiter, Map<String,Object> params, OutputStream outputStream)
      Calls the global data source endpoint to execute a query against a data source with the given parameters.
      Parameters:
      query - the query
      includeHeaders - whether to include headers in the result
      delimiter - the delimiter (currently only space and tab are supported by the server, you can use constants in EssDataSourceImpl for convenience)
      params - the parameters, if any. If none, supply an empty map
      outputStream - the output stream to write results to

    • getServerLogTypes

      List<String> getServerLogTypes()
      The kinds of server log this deployment offers, each a value for the other two methods here.

      Empty rather than an error when the server has no server-level logs at all. They are not universal: both servers this was developed against answer 404 to every /logs path while serving application logs perfectly well, so "this deployment doesn't have them" is an ordinary answer and not a failure. A caller should ask this before offering the feature.

      Returns:
      the server log types, empty if this deployment serves none

    • downloadLatestServerLog

      void downloadLatestServerLog(String serverType, OutputStream outputStream)
      Writes the latest server log of the given type to the stream.
      Parameters:
      serverType - one of getServerLogTypes()
      outputStream - where to write it

    • downloadServerLogsAsZip

      void downloadServerLogsAsZip(String serverType, OutputStream outputStream)
      Writes every server log of the given type, as a zip, to the stream.
      Parameters:
      serverType - one of getServerLogTypes()
      outputStream - where to write it

    • getMdxFunctions

      List<EssMdxFunctionGroup> getMdxFunctions()
      The MDX functions this server understands, in the server's own groups.

      A property of the server's MDX dialect, not of any cube - the same server answers byte-for-byte identically whichever cube is asked. There is no server-level endpoint for it though, so this finds a cube and asks through that; a stopped application will do, since the answer does not depend on the data.

      Returns:
      the function groups, in the order the server listed them
      Throws:
      EssApiException - if the server has no cube to ask through

    • getMcp

      EssMcp getMcp()
      The MCP server built into this Essbase, if it has one.

      Points the opposite way from EssCube.getAi(): this is Essbase offering itself as a tool provider to somebody else's model, rather than Essbase calling out to one. A server can have this working while every /ai endpoint is unconfigured, and usually does.

      Returns:
      the MCP server, which answers isAvailable() false on anything before 26.1

    • getAi

      EssServerAi getAi()
      This server's own generative-AI setup: whether it supports AI, whether it is switched on, which capabilities are on, and whether any GenAI connection has been configured.

      The server-level answer to a question EssCube.getAi() can only answer per cube. The cube walks the whole setup chain, so asking it "is AI configured here" costs one walk per cube and mixes the server's answer in with each application's. This is the half that is the same for every cube on the server, asked once.

      Returns:
      the server's AI setup, never null; nothing is contacted until it is asked something

    • getMaintenanceLimits

      EssMaintenanceLimits getMaintenanceLimits()
      What the server reports about the machine it runs on - free disk and memory, and any configured ceilings. The only window the REST API offers onto the host.
      Returns:
      the limits

    • getLogSettings

      List<EssLogSetting> getLogSettings()
      How each ODL log handler rotates.

      Worth having beside the logs themselves: a handler holding ten megabytes per file and five hundred in total has silently discarded everything older, and nothing in the log says so.

      Returns:
      one entry per handler

    • setLogSettings

      void setLogSettings(List<EssLogSetting> settings)
      Changes how the log handlers rotate.

      Send every handler, not only the changed one - this replaces the set. Start from getLogSettings() and use EssLogSetting.withSizes(java.lang.Integer, java.lang.Integer) on the one being altered.

      Parameters:
      settings - the full set of handlers