Loads one or more local or remote JSDO 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 called asynchronously and can be called either before or after the JSDOSession object has successfully established a login session using its login( ) method. If a JSDO catalog is stored remotely in the Mobile Web application, the recommended practice is to log into the Web application before calling this method.
The URI of a JSDO catalog file, which can specify either a location (remote) in a Web application running on a Web server or a location (local) that is relative to where the App is currently running. 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 JSDOSession object has already logged in and the Mobile App is Web App deployed to the same Apache Tomcat server as the Mobile Web application, you can specify a URI that is relative to the deployment end point (Tomcat server domain or host and port), for example: /SportsMobileApp/static/mobile/OrderEntrySvc.json, where /SportsMobileApp is the location of the Web application.
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 Mobile Web App deployed to a different Web server from any Web application to which the JSDOSession object has already logged in, you must specify an absolute URI that includes the Tomcat server domain or host and port, for example, http://www.progress.com:8980/SportsMobileApp/static/mobile/OrderEntrySvc.json, or perhaps for testing, http://testmach:8980/SportsMobileApp/static/mobile/OrderEntrySvc.json.
Note: The default catalog URI for a catalog created for an OpenEdge Mobile service, relative to the Apache Tomcat server domain or host and port where the session is logged in, is the following: /MobileWebApplicationName/static/mobile/ServiceName.json, where MobileWebApplicationName is the name of the Mobile Web application and ServiceName is the name of the Mobile service for which the JSDO catalog is created.
Note: For the catalog-uri parameter, 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 somewhere other than in the Web application to which the object is logged in.
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.
catalog-uris
An array of strings, each of which is the URI for a catalog as defined for the catalogURI parameter. All of the catalogs in the array must be accessible without specifying credentials. This can be either because they are unprotected, or because the JSDOSession object has already logged into the Web application where they are located.
Note: You can read the catalogURIs property to return the URIs for all catalogs previously loaded into the JSDOSession object.
Promise method signatures
Following are the signatures of methods that are observed in the jQuery Promise that addCatalog( ) returns:
Syntax:
done: function ( session , result , details ) fail: function ( session , result , details ) always: function ( session , result , details )
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.
details
An array of JavaScript objects that contain information on the JSDO 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.
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.
errorObject — Any error object thrown while attempting to load the catalog.
xhr — A reference to the XMLHttpRequest object used to load the catalog from a Web server.
Note: When addCatalog( ) is requested to load a JSDO catalog that is already loaded, it does not load the catalog again. This is considered to be a successful execution. That is, the done( ) method is called, although the result value in the details object for the catalog is progress.data.Session.CATALOG_ALREADY_LOADED.
Example
The following code fragment calls the addCatalog(myCatalogURIs) method on the JSDOSession object, mySession, to load multiple JSDO 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.SUCCESS || progress.data.Session.CATALOG_ALREADY_LOADED) { alert("Catalog successfully loaded: " + details[i].catalogURI); } else 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;
progress.data.Session.SUCCESS — Each catalog specified by the catalogURI or catalogURIs parameter of addCatalog( ) has been loaded successfully or has already been loaded.