Package com.appliedolap.essbase

Interface EssCube

All Superinterfaces:
EssObject
All Known Implementing Classes:
EssCubeImpl
public interface EssCube extends EssObject

  • Method Details

    • getCalcScripts

      List<EssScript> getCalcScripts()
      Get the list of scripts associated with this cube.
      Returns:
      the scripts on this cube

    • calculate

      void calculate()
      Runs the default calculation, aggregating the cube.

      Worth knowing when a freshly built cube looks empty: loading data does not aggregate it. A data load or an application workbook import writes level 0 and stops there, so every upper level reads #Missing until something calculates - which is most of what an ad hoc grid shows when it first opens.

      Blocks until the calculation finishes, because a calculation that has been started and a cube that has been calculated are different things and the caller almost always means the second.

    • calculate

      void calculate(String script)
      Runs a calculation given as script text rather than a stored script.

      EssScript.execute() runs one that exists on the cube; this runs one that does not have to. The two are parameterised differently and neither is guessable - a stored calculation goes in the job's file parameter by bare name, while script text goes in script with isScriptContent set.

      Parameters:
      script - the calculation, e.g. CALC ALL;

    • getMdxScripts

      List<EssScript> getMdxScripts()
      The MDX scripts on this cube. Same endpoints as the calc scripts, told apart by a type parameter - see EssScript.ScriptType.
      Returns:
      the MDX scripts

    • getScripts

      List<EssScript> getScripts(EssScript.ScriptType scriptType)
      The scripts of one kind on this cube.
      Parameters:
      scriptType - which kind
      Returns:
      the scripts

    • createScript

      EssScript createScript(EssScript.ScriptType scriptType, String name, String content)
      Creates a script on this cube.
      Parameters:
      scriptType - which kind
      name - the script name, without an extension
      content - the script text
      Returns:
      the script as created

    • getApplication

      EssApplication getApplication()
      Gets the parent application of this cube.
      Returns:
      the parent application

    • getSessions

      List<EssSession> getSessions()
      Gets the list of sessions on this cube.
      Returns:
      the current cube sessions

    • killSessions

      void killSessions(boolean logoff)
      Ends every session on this cube, leaving the rest of the application's alone.

      What you want before restructuring: the server takes the application and database as filters, so this is one call rather than a walk over getSessions() killing each.

      Parameters:
      logoff - true to disconnect the users as well as ending their requests

    • getAliasTables

      List<String> getAliasTables()
      Gets the names of this cube's alias tables.

      Always at least Default, which is the table a cube has whether or not anyone has added others, and the one members are labelled from when none is asked for.

      Returns:
      the alias table names

    • getVariables

      List<EssCubeVariable> getVariables()

    • createVariable

      EssCubeVariable createVariable(String name, String value)
      Defines a new variable on this cube, shadowing any application or server variable of the same name for anything running against it.
      Parameters:
      name - the variable name
      value - its value
      Returns:
      the created variable

    • getEffectiveVariables

      List<EssEffectiveVariable> getEffectiveVariables()
      Every variable this cube can actually see, with the definition that wins and the ones it hides.

      Three requests, merged here, because the server will not do it: each variable endpoint reports only its own level, so nothing on the server can tell you which definition of a name a query against this cube would resolve to. Nearest wins - cube over application over server.

      Returns:
      one entry per distinct name, ordered by name

    • getOutline

      EssOutline getOutline()
      Gets an outline object for this cube.
      Returns:
      an outline object

    • isScenariosEnabled

      boolean isScenariosEnabled()
      Checks if this cube has scenarios enabled.
      Returns:
      true if scenarios are enabled, false otherwise

    • createDrillthroughURL

      EssDrillthrough createDrillthroughURL(String urlName, String urlLink, List<String> drillRegions)
      Creates a URL-type drill-through on the cube,
      Parameters:
      urlName - the name (no spaces?!)
      urlLink - the drill-through link
      drillRegions - the drillable regions
      Returns:
      a new drill-through object

    • createDrillthroughDataSource

      EssDrillthrough createDrillthroughDataSource(String name, String dataSourceName, List<String> columns, Map<String,EssDrillthroughColumnMapping> columnMappings, List<String> drillRegions)
      Creates a drill-through report that reads its detail from a data source.

      The other half of createDrillthroughURL(java.lang.String, java.lang.String, java.util.List<java.lang.String>): where that one records a URL for a client to open, this one Essbase can execute itself, returning the rows behind a cell - see EssDrillthrough.execute(java.util.Map).

      The data source must already exist; naming one that does not is refused outright with No datasource exists with name '...'.

      Parameters:
      name - the report name
      dataSourceName - the data source holding the detail
      columns - the source columns to return, in order
      columnMappings - which column is filtered by which dimension, keyed by column name
      drillRegions - the regions whose cells may be drilled
      Returns:
      the created report

    • getDrillthroughs

      List<EssDrillthrough> getDrillthroughs()
      Get list of drill-through reports on the cube.
      Returns:
      the list of cube drill-through reports

    • getDrillthrough

      EssDrillthrough getDrillthrough(String drillthroughName)
      Gets a drill-through report with a specific name. Note that the current implementation of this method hits the drill-through report list endpoint and filters based on the name, so you will likely end up with two trips to the server: one to get the list, and one to get the details of the report, which will happen when you access most detailed properties in the drill-through report.
      Parameters:
      drillthroughName - the name of the drill-through report
      Returns:
      a drill-through report object

    • getScenarios

      List<EssScenario> getScenarios()
      Gets the list of scenarios on the cube, if any.
      Returns:
      the cube's scenarios

    • getMember

      EssMember getMember(String memberName)
      Gets a reference to a particular member in the cube outline. This method is likely to change in the future as the outline management and other classes come in to focus, to say nothing of how member IDs and unique members and such will need to be handled.
      Parameters:
      memberName - the name of the member
      Returns:
      the member

    • getDimensions

      List<EssDimension> getDimensions()
      Gets the list of dimensions on the cube, if any.
      Returns:
      the cube's dimensions

    • getLockedObjects

      List<EssLock> getLockedObjects(Integer offset, Integer limit)
      List Locked Objects Returns all the locked objects from the specified application and database
      Parameters:
      offset - Number of items to omit from the start of the result set. Default value is 0
      limit - Maximum number of objects to return. Default is 50
      Returns:
      LockObjectLis

    • unlockObject

      void unlockObject(EssLock lockedObject)
      Unlock Object Unlocks the object in the specified application and database
      Parameters:
      lockedObject - Details about object to be unlocked

    • lockObject

      void lockObject(EssLock unlockedObject)
      Lock Object Locks the object in the specified application and database and returns the details of the locked object
      Parameters:
      unlockedObject - Object details to be locked (required)

    • exportExcel

      String exportExcel()
      Exports this cube to an application workbook, and waits for the export to finish.

      The workbook is written into the server's own file catalogue, not returned - this is an Essbase job, and jobs leave their output on the server. The returned path is where it landed, ready to hand to EssServer.getFiles() or to download.

      Returns:
      the catalogue path of the workbook, e.g. /applications/Sample/Basic/Basic.xlsx
      Throws:
      EssApiException - if the job fails, carrying the server's reason

    • importExcel

      void importExcel(String path, String filename)
      Updates this cube using an Excel workbook. This API is likely to change soon to take an EssFile reference
      Parameters:
      path - the path
      filename - the filename

    • importFile

      void importFile(File file)
      Acts as a convenience function for uploading a file to a cube's storage folder. The Essbase server maps the file location /applications/AppName/CubeName, which contains the cube files such as calc scripts, load rules, and whatnot.
      Parameters:
      file - the file to upload to the cube

    • executeMdx

      @Deprecated(since="2.1.0") void executeMdx(String query, EssCube.MdxOutputType outputType, EssCubeImpl.MdxOptions mdxOptions, OutputStream outputStream)
      Deprecated.
      since 2.1.0. Its options class lives in the implementation package and was never sent. Use executeMdx(String, EssMdxOptions, MdxOutputType, OutputStream).
      Runs an MDX query and writes the server's answer, in the given format, to a stream.
      Parameters:
      query - the query
      outputType - the format to write
      mdxOptions - ignored: this class never sent its options to the server
      outputStream - where to write the result; not closed

    • executeMdx

      void executeMdx(String query, EssMdxOptions options, EssCube.MdxOutputType outputType, OutputStream outputStream)
      Runs an MDX query and writes the server's answer, in the given format, to a stream. JSON is the format executeMdx(String, EssMdxOptions) reads; the others are for handing on as they are.

      The options come second, unlike the deprecated method's, so that a call passing null for those still compiles against the deprecated method rather than matching both.

      Parameters:
      query - the query
      options - how to present the result; EssMdxOptions.defaults() for the server's defaults
      outputType - the format to write
      outputStream - where to write the result; not closed
      Since:
      2.1.0

    • executeMdx

      EssGrid executeMdx(String query)
      Runs an MDX query and returns its cells.

      The grid is an EssMdxGrid, though declared as the plainer type for compatibility. Use executeMdx(String, EssMdxOptions) to have it typed as one.

      Parameters:
      query - the query
      Returns:
      the result

    • executeMdx

      EssMdxGrid executeMdx(String query, EssMdxOptions options)
      Runs an MDX query and returns its cells along with the dimensions on each axis.
      Parameters:
      query - the query
      options - how to present the result; EssMdxOptions.defaults() for the server's defaults
      Returns:
      the result
      Since:
      2.1.0

    • getAi

      EssCubeAi getAi()
      The generative-AI features this cube offers - notably turning a question asked in English into an MDX query.

      Returns a handle whether or not the server supports or has been set up for any of this; ask the handle's EssCubeAi.getReadiness() rather than expecting this to fail or return null, since "can this cube use AI" is a question with several different answers and several different people who can fix them.

      Returns:
      the cube's AI features, never null

    • getStatus

      EssApplication.Status getStatus()
      Whether this cube is started.

      A cube has a state of its own and does not simply inherit its application's: an application can be started with a cube inside it stopped, and only a started cube answers queries. Shares EssApplication.Status because the server reports both with the same vocabulary.

      Returns:
      the cube's status, EssApplication.Status.UNKNOWN for a state this doesn't name

    • openCubeView

      EssCubeView openCubeView()
      Opens a live, ad hoc grid view on this cube using its default layout - the REST analog of the Java API's IEssCube.openCubeView.
      Returns:
      a navigable cube view

    • openCubeView

      EssCubeView openCubeView(String layoutName)
      Opens a live, ad hoc grid view on this cube using a specific saved layout by name, rather than whatever is currently saved as "Default".
      Parameters:
      layoutName - the name of the saved layout to open
      Returns:
      a navigable cube view

    • resetDefaultView

      void resetDefaultView()
      Resets openCubeView()'s "default grid" back to the true stateless default (the first grid you'd see in an ad hoc analysis, before any grid operations).

      Despite its Swagger documentation, "Get Default Grid" is not actually stateless: every grid operation (zoom, pivot, etc.) is silently persisted server-side into a hidden, per-user layout named Session_Layout_<username> - hidden meaning it never appears in GET .../layouts, even though both "Get Default Grid" and "Execute Layout Grid" read from it. Deleting that layout by its exact name is the only way found so far to restore the documented stateless behavior. The delete call itself is not idempotent (it 400s with "No layout exists..." if there's nothing to delete), but this method treats that specific case as success, since the desired end state - no session layout - already holds.

    • getMdxFunctions

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

      Reference material rather than anything about this cube: the endpoint is cube-scoped, but a given server answers identically for every cube, and for a stopped application too. Offered here because this is where the path lives, and on EssServer.getMdxFunctions() because that is what it actually describes.

      Returns:
      the function groups, in the order the server listed them

    • refreshStatus

      EssApplication.Status refreshStatus()
      Asks the server for this cube's status again, and updates this object with the answer.

      Same reason as EssApplication.refreshStatus(): a cube's status is a snapshot, and browsing into a cube starts the application that owns it, so the snapshot goes stale through ordinary use.

      Returns:
      the status as of now

    • start

      void start()
      Starts this cube, and with it the application that owns it - a cube cannot run in a stopped application, so the server starts both.

    • stop

      void stop()
      Stops this cube, leaving its application running.

      Not the mirror of start(), and verified against a live server: starting a cube starts its application, but stopping one leaves the application started with its other cubes untouched. To stop the application as well, stop the application.

    • batchOutlineEdit

      EssBatchOutlineEditResult batchOutlineEdit(String xml)
      Applies a batch outline edit document to this cube's outline.

      Batch outline editing is Essbase's way of making many outline changes in one transaction: one document listing add, update, delete, rename, move and attribute-association actions, sent once and applied in order, instead of a request per member. The document is XML in the mbredit namespace, the same format Essbase's own mbredit.xsd defines - and, as it turns out, the same format EPM Cloud writes when it exports a Planning application's Essbase outline, so a document from one can be replayed against the other.

      Read the result. This call throws only when the request itself fails. An edit whose actions could not be applied comes back as HTTP 200 carrying an error log, so the return value is the only place the outcome exists - see EssBatchOutlineEditResult.

      Sent as XML rather than JSON although the endpoint advertises both. The JSON form the server documents is a JAXB artifact - each action wrapped in a name/value pair - and posting it is accepted with HTTP 200 and applies nothing at all.

      Parameters:
      xml - the document, with otlEditMain as its root element
      Returns:
      what the server said it did

    • batchOutlineEdit

      EssBatchOutlineEditResult batchOutlineEdit(EssBatchOutlineEdit edit)
      Applies a batch outline edit built with EssBatchOutlineEdit.

      The same call as batchOutlineEdit(String) - and the same warning about reading the result - with the document written for you.

      Parameters:
      edit - the actions to apply, in order
      Returns:
      what the server said it did