Class sap.ui2.srvc.Catalog

Defined in: catalog.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	sap.ui2.srvc.Catalog(oFactory, vCatalogData) Constructs a new representation (wrapper) of the CHIP catalog with the given ID to be loaded from the given factory's page building service.

Method Summary
Method Attributes	Method Name and Description
	clone(sNewDomainId, sNewTitle, fnSuccess, fnFailure) Creates a new catalog in the backend as a clone of this catalog, using the given domain ID.
	getCachedRemoteFailureArguments() In case of a remote catalog which failed for some reason to read its CHIPs (see #readChips), this method can be used to retrieve the original failure handler arguments.
	getCatalogData() Returns all of this catalog's properties or `undefined` if only the catalog's ID is known.
	getCatalogPage() Returns this catalog's corresponding catalog page (typically a stub only), if any (see sap.ui2.srvc.Factory#createNewPageBasedCatalog).
	getChips() Returns this catalog's CHIPs (typically stubs only).
	getDomainId() Returns this catalog's domain ID which represents the catalog ID without any type-specific prefixes (like "X-SAP-REMOTE:").
	getId() Returns this catalog's technical ID.
	getTitle() Returns this catalog's title.
	getType() Returns this catalog's type.
	isOutdated() Tells whether this catalog is marked as outdated.
	isReadOnly() Tells whether this catalog is readOnly.
	isStub() Tells whether this catalog is still only a stub and does not yet know its CHIPs or title.
	load(fnSuccess, fnFailure) Loads the catalog from the page building service, including its title and its contained CHIPs (at least as stubs).
	readChips(aChipIds, fnSuccess, fnFailure) Reads all CHIPs into the factory's CHIP cache.
	refresh(fnSuccess, fnFailure) Refreshes the catalog's CHIPs by reading them (again) from the backend.
	remove(fnSuccess, fnFailure) Removes this catalog by deleting it within the page building service.
	toString(bVerbose) Returns this catalog's string representation.
	update(oCatalogData, fnSuccess, fnFailure) Updates one or more properties of this catalog in the backend based on the given raw data.

Class Detail

sap.ui2.srvc.Catalog(oFactory, vCatalogData)

Constructs a new representation (wrapper) of the CHIP catalog with the given ID to be loaded from the given factory's page building service.

Initially a stub is created, which can later load its properties and related objects asynchronously.

Catalogs are currently read-only and cannot be updated through the page building service.

Parameters:
{sap.ui2.srvc.Factory} oFactory: the factory
{object|string} vCatalogData: the catalog's ID or its catalog data as loaded via page building service

Since:: 1.2.0

See:: sap.ui2.srvc.PageBuildingService; sap.ui2.srvc.Chip

Method Detail

clone(sNewDomainId, sNewTitle, fnSuccess, fnFailure)

Creates a new catalog in the backend as a clone of this catalog, using the given domain ID. All copied catalog CHIPs are references (see sap.ui2.srvc.Chip#isReference) until they are changed (copy on write). Changes to the original CHIPs will be visible in the catalog copy after the next read. The success handler is called as soon as the clone has been created and the new sap.ui2.srvc.Catalog object is not a stub anymore. Access the sap.ui2.srvc.Catalog instance passed to the success callback in order to learn the resulting ID!

Can be called no matter whether this catalog is still a stub. For remote catalogs where only the ID is known, this method currently fails!

Parameters:
{string} sNewDomainId: the new catalog's domain-specific ID which must not contain a colon
{string} sNewTitle Optional: the new catalog's title; if undefined, this catalog's title will be used
{function (sap.ui2.srvc.Catalog)} fnSuccess: success handler for asynchronous creation
{function (string|[sap.ui2.srvc.Catalog]|[object])} fnFailure: error handler, taking an error message, an optional sap.ui2.srvc.Catalog instance and, since version 1.28.6, an optional object containing the complete error information.
See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details about the complete error information parameter.

Since:: 1.19.1

See:: #getCatalogPage

{arguments} getCachedRemoteFailureArguments()

In case of a remote catalog which failed for some reason to read its CHIPs (see #readChips), this method can be used to retrieve the original failure handler arguments. This is needed because of the graceful degradation (the catalog keeps usable and simply behaves as if it would be empty). Will be reset on call of #update.

Since:: 1.34.0

Returns:: {arguments} the arguments as originally received by the #readChips failure handler

See:: #readChips

{object} getCatalogData()

Returns all of this catalog's properties or undefined if only the catalog's ID is known.

Since:: 1.19.1

Returns:

{object} all of this catalog's properties, e.g.

  {
    baseUrl: "/sap/hba/apps/kpi/s/odata/hana_chip_catalog.xsodata/",
    domainId: "Z_REMOTE_HANA_CATALOG",
    remoteId: "HANA_CATALOG",
    systemAlias: "sanssouci",
    title: "Remote HANA catalog",
    type: "REMOTE"
  }

See:: #update; sap.ui2.srvc.Factory#createNewCatalog

{sap.ui2.srvc.Page} getCatalogPage()

Returns this catalog's corresponding catalog page (typically a stub only), if any (see sap.ui2.srvc.Factory#createNewPageBasedCatalog). This method is intended to be called in a design time use case only.

Catalog pages are an easy way to modify catalogs. A catalog based on a catalog page is not only represented by a sap.ui2.srvc.Catalog, but also by a sap.ui2.srvc.Page. This means that you can use the sap.ui2.srvc.Page and sap.ui2.srvc.ChipInstance APIs to modify the catalog. For example, you can add a new sap.ui2.srvc.Chip as a sap.ui2.srvc.ChipInstance using the sap.ui2.srvc.Page#createNewPageBasedCatalog method.

Can safely be called if the catalog itself is not a stub anymore (#isStub). Must not be called if only the catalog's ID is known (see #getCatalogData)!

Since:: 1.19.1

Returns:: {sap.ui2.srvc.Page} this catalog's corresponding catalog page, or undefined if this catalog is not based on a catalog page

{sap.ui2.srvc.Chip[]} getChips()

Returns this catalog's CHIPs (typically stubs only). Can be called only if the catalog itself is not a stub anymore.

Since:: 1.2.0

Returns:: {sap.ui2.srvc.Chip[]} this catalog's CHIPs

See:: #isStub

{string} getDomainId()

Returns this catalog's domain ID which represents the catalog ID without any type-specific prefixes (like "X-SAP-REMOTE:"). The domain ID is better human-readable than the ID (see #getId()). Returns undefined as long as only the ID of this catalog is known.

Since:: 1.19.1

Returns:: {string} this catalog's domain ID

See:: sap.ui2.srvc.Factory#createNewPageBasedCatalog; sap.ui2.srvc.PageBuildingService#createPageBasedCatalog

{string} getId()

Returns this catalog's technical ID. In contrast to #getDomainId this method returns the ID including type-specific prefixes (like "X-SAP-REMOTE:"). Those should not be displayed on a UI, for example.

Since:: 1.2.0

Returns:: {string} this catalog's technical ID including type-specific prefixes (like "X-SAP-REMOTE:")

{string} getTitle()

Returns this catalog's title.

Can safely be called if the catalog itself is not a stub anymore (#isStub). Must not be called if only the catalog's ID is known (see #getCatalogData)!

Since:: 1.2.0

Returns:: {string} this catalog's title

See:: #isStub

{string} getType()

Returns this catalog's type.

Can safely be called if the catalog itself is not a stub anymore (#isStub). Must not be called if only the catalog's ID is known (see #getCatalogData)!

Since:: 1.16.4

Returns:: {string} this catalog's type

{boolean} isOutdated()

Tells whether this catalog is marked as outdated. For a catalog based on a catalog page (see #getCatalogPage), this means that the catalog page is marked as outdated (see sap.ui2.srvc.Page#isOutdated).

Can safely be called if the catalog itself is not a stub anymore (#isStub). Must not be called if only the catalog's ID is known (see #getCatalogData)!

Since:: 1.19.1

Returns:: {boolean} whether this catalog is marked as outdated

{boolean} isReadOnly()

Tells whether this catalog is readOnly.

Can safely be called if the catalog itself is not a stub anymore (#isStub). Must not be called if only the catalog's ID is known (see #getCatalogData)!

Since:: 1.32.0

Returns:: {boolean} true if this catalog is in read only mode

{boolean} isStub()

Tells whether this catalog is still only a stub and does not yet know its CHIPs or title.

Since:: 1.2.0

Returns:: {boolean} whether this catalog is still only a stub

See:: #load

load(fnSuccess, fnFailure)

Loads the catalog from the page building service, including its title and its contained CHIPs (at least as stubs). Must not be called twice! If needed, call refresh().

Parameters:
{function ()} fnSuccess: no-args success handler
{function (string|[object])} fnFailure Optional: error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. Default: see sap.ui2.srvc.ODataService#getDefaultErrorHandler

Since:: 1.2.0

See:: #isStub; #refresh

readChips(aChipIds, fnSuccess, fnFailure)

Reads all CHIPs into the factory's CHIP cache. The catalog itself remains unchanged. This method may be called even if the catalog is a stub.

Parameters:
{string[]} aChipIds: the IDs of the CHIPs to be read.
{function ()} fnSuccess: no-args success handler
{function (string|[object])} fnFailure Optional: error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. Please see also #getCachedRemoteFailureArguments. Default: see sap.ui2.srvc.ODataService#getDefaultErrorHandler

Since:: 1.16.4

See:: #getCachedRemoteFailureArguments

refresh(fnSuccess, fnFailure)

Refreshes the catalog's CHIPs by reading them (again) from the backend. The catalog may be a stub before refresh (since 1.19.0), but is not a stub anymore once refresh succeeds.

When a catalog is still a stub, refresh is the same as load. When the catalog has been loaded before, refresh fetches only the CHIPs.

Parameters:
{function ()} fnSuccess: no-args success handler
{function (string|[object])} fnFailure Optional: error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. Default: see sap.ui2.srvc.ODataService#getDefaultErrorHandler

Since:: 1.11.0

See:: #load

remove(fnSuccess, fnFailure)

Removes this catalog by deleting it within the page building service. Also deletes the corresponding catalog page, if applicable (see #getCatalogPage and sap.ui2.srvc.Factory#createNewPageBasedCatalog).

BEWARE: Do not continue to use this object afterwards!

Can safely be called if the catalog itself is not a stub anymore (#isStub). Must not be called if only the catalog's ID is known (see #getCatalogData) or if the catalog is being refreshed currently (see #refresh)!

Parameters:
{function ()} fnSuccess Optional: no-args success handler
{function (string|[object])} fnFailure Optional: error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. If not given sap.ui2.srvc.ODataService#getDefaultErrorHandler is used

Since:: 1.19.1

{string} toString(bVerbose)

Returns this catalog's string representation.

Parameters:
{boolean} bVerbose Optional, Default: false: flag whether to show all properties

Since:: 1.2.0

Returns:: {string} this catalog's string representation

update(oCatalogData, fnSuccess, fnFailure)

Updates one or more properties of this catalog in the backend based on the given raw data. Properties which are not given keep their current value. Keys cannot be updated this way! Note that for a catalog based on a catalog page (#getCatalogPage), the "title" property is shared between the catalog and its corresponding catalog page!

Can safely be called if the catalog itself is not a stub anymore (#isStub). Must not be called if only the catalog's ID is known (see #getCatalogData)!

The catalog becomes a stub immediately. As soon as the update succeeds, the catalog is loaded automatically and only after that, the success handler is called. It is not wise to keep references to old CHIPs loaded from this catalog before an update that changes the catalog's "identity", e.g. the "remoteId" property of a remote catalog.

Parameters:

{object} oCatalogData

any subset of the catalog's properties, e.g.

  {
    baseUrl: "/sap/hba/apps/kpi/s/odata/hana_chip_catalog.xsodata/",
    domainId: "Z_REMOTE_HANA_CATALOG",
    remoteId: "HANA_CATALOG",
    systemAlias: "sanssouci",
    title: "Remote HANA catalog",
    type: "REMOTE"
  }

{function ()} fnSuccess

no-args success handler

{function (string|[object])} fnFailure Optional

error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. Default: see sap.ui2.srvc.ODataService#getDefaultErrorHandler

Since:: 1.19.1

Throws:
: Error when trying to update the "__metadata" property.

See:: #getCatalogData

Classes

Class sap.ui2.srvc.Catalog