Note: Updated for Progress Data Objects Version 4.4.1 and later.
Loads one or more local or remote Data Service Catalogs into the current JSDOSession object.
The appropriate Catalog must be loaded before creating a JSDO for any resource defined in the Catalog.
If a Catalog is on a web server (remote), this method throws an exception if it is not possible to send a request to the specified web application.
This method is always executed asynchronously and returns results in callbacks that you register using methods of a Promise object returned as the method value.
Note: In order to invoke this method successfully, jQuery Promises must be supported in your development environment. Otherwise, the method throws an exception.
Note: You can call this method either before or after the JSDOSession object has successfully established a JSDO login session using its login( ) method. However, if the Data Service Catalog is stored remotely in the web application that hosts the Data Object Service, Progress recommends that you log into the web application before calling this method.
Note: As a recommended alternative to using this method on an existing JSDOSession object, you can create a new, initialized JSDOSession using the progress.data.getSession( ) stand-alone function. In one call, this function instantiates the object, invokes its login( ) method with specified credentials, then invokes its addCatalog( ) method to load a specified Data Service Catalog. For more information, see the getSession( ) stand-alone function description.
A string expression that specifies the URI of a Data Service Catalog file. This URI can specify either a location (remote) in a web application running on a web server or a location (local) that is relative to the device where the app is currently running. If the URI specifies a remote location, it is typically the location of the web application that hosts the Data Object Service and where the JSDOSession object has a JSDO login session. If the URI is a relative path (e.g., catalogs/OrderEntrySvc.json), the catalog-uri is assumed to be relative to the location from which the app was loaded.
If the mobile app from which you are logging in is a hybrid app that will be installed to run directly in a native device container, or if it is a web app deployed to a different web server from the web application to which the JSDOSession object has already logged in, you must specify an absolute URI for the Catalog that includes the Tomcat server domain or host and port, for example, http://www.progress.com:8980/SportsMobileApp/static/OrderEntrySvc.json, or perhaps for testing, http://localhost:8980/SportsMobileApp/static/OrderEntrySvc.json.
If the JSDOSession object has already logged in and the mobile app is a web app deployed to the same Apache Tomcat server as the web application that hosts the Data Object Service, you can specify a URI that is relative to the deployment end point (Tomcat server domain or host and port), for example: /SportsMobileApp/static/OrderEntrySvc.json, where /SportsMobileApp is the location of the web application.
Note: The default Catalog URI for a Catalog created for an OpenEdge Data Object Service, relative to the Apache Tomcat server domain or host and port where the session is logged in, is the following: /WebApplicationName/static/ServiceName.json, where WebApplicationName is the name of the web application and ServiceName is the name of the Data Object Service for which the Data Service Catalog is created.
catalog-uris
An array of string expressions, each of which is the URI for a Catalog as defined for the catalogURI parameter. If any of the Catalogs in the array are protected separately from the web application where the JSDOSession object is logged in, you can specify the additional credentials using cat-user-name and cat-password.
Note: You can read the catalogURIs property to return the URIs for all Catalogs previously loaded into the JSDOSession object.
cat-user-name
A string expression containing a user ID to authenticate access to a protected Catalog. If you do not specify cat-user-name, Catalog access is authorized using existing user credentials (if any).
cat-password
A string expression containing a password (if required) to authenticate the user specified by cat-user-name.
parameter-object
An object that contains the following optional property:
iOSBasicAuthTimeout — A number that specifies the time, in milliseconds, that the addCatalog( ) method waits for a response before returning an error. This error might mean that the user entered invalid credentials to access a protected Catalog URI. If you set this value to zero (0), no timeout is set, and addCatalog( ) can wait indefinitely before returning an error. If you do not set the iOSBasicAuthTimeout property, addCatalog( ) uses 4000 (4 seconds) as the default value.
Any non-zero timeout value (default or otherwise) for this parameter-object property operates only under certain conditions. Otherwise, any setting of this property has no effect. For more information, see the notes of the progress.data.JSDOSession class description.
Note: If the JSDOSession object is already logged in, you typically do not need to specify cat-user-name and cat-password. These optional parameters are available primarily if the object is not yet logged in, or if you store the Catalog someplace on the web other than the web application that hosts the Data Object Service (where the JSDOSession object has a JSDO login session).
Caution: Although you can use a single JSDOSession object to load a Catalog that is stored somewhere on the web other than the web application that hosts the Data Object Service, this typically works only if the Catalog is protected with Anonymous or HTTP Basic authentication.
Promise method signatures
jQuery Promise objects define methods that register a callback function with a specific signature. The callback signatures depend on the method that returns the Promise. Following are the signatures of callbacks registered by methods in any Promise object that addCatalog( ) returns:
Syntax:
promise.done( function ( session , result , details ) )
promise.fail( function ( session , result , details ) )
promise.always( function ( session , result , details ) )
promise
A reference to the Promise object that is returned as the value of the addCatalog( ) method. For more information on Promises, see the notes on Promises in the description of the progress.data.JSDOSession class.
session
A reference to the JSDOSession object on which addCatalog( ) was called.
result
A constant indicating the overall result of the call that can have one of the following values:
progress.data.Session.SUCCESS — Each Catalog specified by the catalogURI or catalogURIs parameter of addCatalog( ) has been loaded successfully or has already been loaded.
progress.data.Session.GENERAL_FAILURE — One or more of the specified Catalogs has failed to load successfully.
Note: It is not always necessary to test the value of result in a Promise method callback for the addCatalog( ) method, especially if the callback is registered using promise.done( ) and promise.fail( ), where each callback always executes with the same value for success (done( )) or failure (fail( )).
details
An array of JavaScript objects that contain information on the Data Service Catalogs that addCatalog( ) attempted to load. Each object has the following properties:
catalogURI — The URI of a specified Catalog.
result — A constant indicating the result of loading the Catalog that can have one of the following values:
progress.data.Session.SUCCESS — The specified Catalog loaded successfully, or has previously been loaded.
progress.data.Session.CATALOG_ALREADY_LOADED — The specified Catalog was previously loaded.
When addCatalog( ) is requested to load a Data Service Catalog that is already loaded, it does not load the Catalog again, but is considered a successful execution. That is, the promise.done( ) callback is called, although the result value in the details object for the specified Catalog is progress.data.Session.CATALOG_ALREADY_LOADED.
progress.data.Session.AUTHENTICATION_FAILURE — The specified Catalog failed to load because of an authentication error.
progress.data.Session.GENERAL_FAILURE — The specified Catalog failed to load because of an error other than an authentication failure.
This value can also be returned if invalid user credentials triggered a Catalog access timeout according to the value of the parameter-object.iOSBasicAuthTimeout property.
errorObject — Any error object thrown while attempting to load the Catalog.
If this object is thrown because of a Catalog access timeout triggered according to the value of the parameter-object.iOSBasicAuthTimeout property, the message property of the error object is set to "addCatalog timeout expired".
xhr — A reference to the XMLHttpRequest object used to load the Catalog from a web server.
Example
The following code fragment calls the addCatalog(myCatalogURIs) method on the JSDOSession object, mySession, to load multiple Data Service Catalogs specified in myCatalogURIs. This example uses try and catch blocks to check any error object thrown prior to requesting the Catalog, and assembles an appropriate message to display in an alert box or does other processing for each case:
try {
mySession.addCatalog( myCatalogURIs ).done( function( session, result, details ) {
alert("All Catalogs loaded.");
}).fail( function( session, result, details ) {
var numCats = details.length;
for ( i = 0; i < numCats; i++ ) {
if (details[i].result === progress.data.Session.AUTHENTICATION_FAILURE) {
alert("Authentication error: " + details[i].catalogURI);
} else if (details[i].result === progress.data.Session.GENERAL_FAILURE) {
alert("General Catalog load error: "
+ details[i].catalogURI);
if (details[i].errorObject) {
// Process thrown error object during load . . .
}
if (details[i].xhr) {
// Process XHR object sent for the load . . .
}
} else {
alert("Not sure what is wrong with "
+ details[i].catalogURI);
}
} // for each load attempt
}); }
catch(errObj) {
var msg;
iOSBasicAuthTimeout — A number that specifies the time, in milliseconds, that the addCatalog( ) method waits for a response before returning an error. This error might mean that the user entered invalid credentials to access a protected Catalog URI. If you set this value to zero (0), no timeout is set, and addCatalog( ) can wait indefinitely before returning an error. If you do not set the iOSBasicAuthTimeout property, addCatalog( ) uses 4000 (4 seconds) as the default value.