Class ecm.model.Request

Extends ecm.model._ModelObject.
Represents a single request to the services. This class is used to manage and maintain information about the request.

The Request class centralizes service requests. The class provides a common way to handle wait indicators and errors. Internally, Request uses XMLHttpRequest or Dojo's xhr to send the request to the server.

Requests are normally sent asynchronously, which prevents the problems that occur when synchronous and asynchronous requests are used together. However, there is the capability to send request synchronously, which should be used only in special situations. Remember that a synchronous request is not necessarily atomic -- an outstanding asynchronous request might be processed while the synchronous request is waiting.

Typically, users do not need to use a Request object directly. Instead, other ecm.model objects use the Request object to invoke services. However, a custom extension might use a Requestobject to invoke a custom services in order to obtain similar behaviors from the services.
Defined in: <ecm\model\Request.js>.

Constructor Summary

Constructor Attributes	Constructor Name and Description
	ecm.model.Request(properties) Constructs a request.

Field Summary

Field Attributes	Field Name and Description
	backgroundRequest A boolean indicating that the request should be processed 'quietly', that is without any progress messages to the user.
	callerHandledErrorNumbers An array of error numbers that will not be notified and are to be handled by the caller.
	cancellable A boolean indicating that the service is cancellable.
	cancelled A boolean indicating that the request has been cancelled.
	cancelMessage A message to display to the user when the cancel button is clicked.
	notifyOnCancel A boolean indicating that for a cancellable request, if the request is cancelled, a notification will be sent to the service, so that the service can clean up and exit.
	progressMessage A message to display to the user while the service is executing on the server.
	repository An instance of ecm.model.Repository for the repository related to this service, or null if this service is not related to a particular repository.
	requestBody String or form object to add to the request body for "POST" requests.
	requestCompleteCallback A function called when the request has completed.
	requestFailedCallback A function called when the request has failed.
	requestHeaders List of name/value pairs to add to the request header.
	requestMethod The HTTP method to be used for the request: GET, PUT, POST, DELETE.
	requestUrl The URL to the service.
	uploadProgress A boolean indicating that the request is added with event listener for upload progress.
	uuid A unique id for the request.
	xmlHttpRequest The associated XMLHttpRequest for this service.

Fields borrowed from class ecm.model._ModelObject:: categorization, id, isRecurring, name, nameFilter, pane, status, type, userId

Method Summary

Method Attributes	Method Name and Description
	addMessage(message) Adds a message to the desktop.
	cancel() Cancels the request.
	constructor()
	dojoIOIFrameDownload(downloadForm) Sends the file download request using iframe.send().
	dojoIOIFrameSend(fileInputForm) Sends the file upload request using iframe.send().
	getReadyState() Returns the state of the request: 1: Sending the request 2: Request sent 3: Receiving the response 4: Response received
	getResponse() Returns the HTTP response as a JavaScript object, after converting the response text, assumed to be in JSON, to a JavaScript object.
	getResponseContentType() Returns the HTTP response Content-Type.
	getResponseProperties() Returns a simple JavaScript object with the HTTP response header properties, if any.
	getResponseStatus() Returns the HTTP response status code.
	getResponseText() Returns the HTTP response text, if any.
	isSameRequestAs(request) Returns true if this request is the same as the passed in request.
	onRequestCompleted(request) An event method invoked when the request completes (either normally or abnormally).
	onRequestStarted(request) An event method invoked when the request is sent.
<static>	ecm.model.Request.Request.appendSecurityToken(url) Append the security token to a url or query string.
<static>	ecm.model.Request.Request.downloadFormServiceAPI(serviceName, repositoryType, params, downloadForm) This static function sends download form data to an IBM Content Navigator service via iframe.send().
<static>	ecm.model.Request.Request.getPluginResourceUrl(pluginName, resourceName) This static function returns a URL that will retrieve a resource from a plug-in's JAR file.
<static>	ecm.model.Request.Request.getSecurityToken(response) Retrieve a security token from a response
<static>	ecm.model.Request.Request.getServiceRequestUrl(serviceName, repositoryType, params) This static function returns a URL appropriate for invoking an IBM Content Navigator service.
<static>	ecm.model.Request.Request.ieFileUploadServiceAPI(serviceName, repositoryType, params, fileInputForm) This static function creates and sends form data to an IBM Content Navigator service via iframe.send().
<static>	ecm.model.Request.Request.invokePluginService(pluginName, pluginServiceName, pluginParams) This static function invokes the services to launch a plug-in-provided service.
<static>	ecm.model.Request.Request.invokePluginServiceSynchronous(pluginName, pluginServiceName, pluginParams) This static function will synchronously invoke the services to launch a plug-in-provided service.
<static>	ecm.model.Request.Request.invokeServiceAPI(serviceName, repositoryType, params) This static function creates and sends a request to an IBM Content Navigator service via HTTP GET.
<static>	ecm.model.Request.Request.isNativeClient() This static function returns whether the client is the native like iOS or Android or Web based.
<static>	ecm.model.Request.Request.postFormToPluginService(pluginName, pluginServiceName, form, pluginParams) This static function creates and sends form data to a plug-in service via HTTP POST.
<static>	ecm.model.Request.Request.postFormToServiceAPI(serviceName, repositoryType, params, form) This static function creates and sends form data to an IBM Content Navigator service via HTTP POST.
<static>	ecm.model.Request.Request.postPluginService(pluginName, pluginServiceName, contentType, pluginParams) This static function will invoke the services to launch a plug-in provided service.
<static>	ecm.model.Request.Request.postServiceAPI(serviceName, repositoryType, contentType, params) This static function creates and sends a request to an IBM Content Navigator service via HTTP POST.
<static>	ecm.model.Request.Request.postSynchronousPluginService(pluginName, pluginServiceName, contentType, pluginParams) This static function will synchronously invoke the services to launch a plug-in provided service.
<static>	ecm.model.Request.Request.setNativeClient(isNativeClient) This static function set whether the client is the native like iOS or Android or Web based.
<static>	ecm.model.Request.Request.setSecurityToken(params) Adds a security token to request parameters
	responseIsHtml() Returns true if the response Content-Type contains "text/html".
	retry() Reruns the request.
	send(params) Sends the request to the server.

Methods borrowed from class ecm.model._ModelObject:: destroy, getSortCriteria, onChange, own, refresh, toString

Constructor Detail

ecm.model.Request(properties)

Constructs a request. Typically one of the static 'invoke' or 'post' methods is used to construct a request.

Parameters:
properties: the properties for the request. The properties can be any of the public fields as defined below and on ecm.model._ModelObject.

Field Detail

backgroundRequest

A boolean indicating that the request should be processed 'quietly', that is without any progress messages to the user.

callerHandledErrorNumbers

An array of error numbers that will not be notified and are to be handled by the caller.

Since:: 2.0.2

cancellable

A boolean indicating that the service is cancellable. A progress dialog will normally display a cancel button to the user for cancellable services.

cancelled

A boolean indicating that the request has been cancelled.

cancelMessage

A message to display to the user when the cancel button is clicked.

notifyOnCancel

A boolean indicating that for a cancellable request, if the request is cancelled, a notification will be sent to the service, so that the service can clean up and exit.

Since:: 2.0.3.5

progressMessage

A message to display to the user while the service is executing on the server.

repository

An instance of ecm.model.Repository for the repository related to this service, or null if this service is not related to a particular repository.

requestBody

String or form object to add to the request body for "POST" requests.

requestCompleteCallback

A function called when the request has completed. The response object is passed to this function as the only argument.

requestFailedCallback

A function called when the request has failed. The error data and an array of ecm.model.message error messages are passed as parameters to this function. If there are no error messages then the error message array parameter is omitted.

requestHeaders

List of name/value pairs to add to the request header.

requestMethod

The HTTP method to be used for the request: GET, PUT, POST, DELETE.

requestUrl

The URL to the service.

uploadProgress

A boolean indicating that the request is added with event listener for upload progress.

uuid

A unique id for the request. This is generated automatically during construction, so this field should be considered read-only.

xmlHttpRequest

The associated XMLHttpRequest for this service. This is constructed as a part of invoking Request.send, so this field should be considered read-only.

Method Detail

addMessage(message)

Adds a message to the desktop.

Parameters:
message

cancel()

Cancels the request. Note that the request may have already been sent, in which case this will cancel the handling of the reply by the browser and may or may not cause the server to abort processing of the request.

constructor()

dojoIOIFrameDownload(downloadForm)

Sends the file download request using iframe.send().

Parameters:
downloadForm: The form for the download request.

Since:: 2.0.3.5

dojoIOIFrameSend(fileInputForm)

Sends the file upload request using iframe.send().

Parameters:
fileInputForm: The form containing the file input field and properties needed for add document.

getReadyState()

Returns the state of the request:

1: Sending the request
2: Request sent
3: Receiving the response
4: Response received

getResponse()

Returns the HTTP response as a JavaScript object, after converting the response text, assumed to be in JSON, to a JavaScript object.

getResponseContentType()

Returns the HTTP response Content-Type. This is only valid after the ready state is 4 (response received).

Since:: 2.0.2

getResponseProperties()

Returns a simple JavaScript object with the HTTP response header properties, if any. This is only valid after the ready state is 4 (response received).

getResponseStatus()

Returns the HTTP response status code. This is only valid after the ready state is 4 (response received).

getResponseText()

Returns the HTTP response text, if any. This is only valid after the ready state is 4 (response received).

isSameRequestAs(request)

Returns true if this request is the same as the passed in request.

Parameters:
request

onRequestCompleted(request)

An event method invoked when the request completes (either normally or abnormally). This is intended to be used for updating status indicators.

Parameters:
request

onRequestStarted(request)

An event method invoked when the request is sent. This is intended to be used to cause status indicators to update in order to show that the request has started.

Parameters:
request

<static> ecm.model.Request.Request.appendSecurityToken(url)

Append the security token to a url or query string.

Parameters:
url: The url or query string. If blank, or there are no parameters on the requst, the token is appended using "?", otherwise, it is appended using "&".

Returns:: The resulting url

<static> ecm.model.Request.Request.downloadFormServiceAPI(serviceName, repositoryType, params, downloadForm)

This static function sends download form data to an IBM Content Navigator service via iframe.send().

You can use this method to submit the HTML form to upload a file to the IBM Content Navigator add document service.

Parameters:

serviceName

The name of the service. Refer to navigator/WEB-INF/struts.xml for a list of the services.

repositoryType

The type of content repository: od, cm, p8, ci, cmis, or undefined for common services.

params

An object containing additional parameters and request callbacks. Parameters include:

requestParams - Object containing any request parameters that should be added to the form post.
cancellable - Flag indicating if the request can be canceled.
backgroundRequest - Flag indicating if the request should be run in the background.
requestCompleteCallback - Callback method called when the a response from the server is received.
requestFailedCallback - Callback method called when a request returns from the server with errors.

downloadForm

The download form to post. Form is an instance of FormData.

Since:: 2.0.3.5

<static> ecm.model.Request.Request.getPluginResourceUrl(pluginName, resourceName)

This static function returns a URL that will retrieve a resource from a plug-in's JAR file.

Parameters:
pluginName: The identifier of the plug-in.
resourceName: The name of the resource (include any path information beyond the WebContent directory).

<static> ecm.model.Request.Request.getSecurityToken(response)

Retrieve a security token from a response

Parameters:
response: The response object

Returns:: The security token

<static> ecm.model.Request.Request.getServiceRequestUrl(serviceName, repositoryType, params)

This static function returns a URL appropriate for invoking an IBM Content Navigator service.

Parameters:
serviceName: The name of the service. Refer to navigator/WEB-INF/struts.xml for a list of the services.
repositoryType: The type of content repository: od, cm, p8, cmis, a plug-in provided repository type, or undefined for common services.
params: An object containing additional parameters.

<static> ecm.model.Request.Request.ieFileUploadServiceAPI(serviceName, repositoryType, params, fileInputForm)

This static function creates and sends form data to an IBM Content Navigator service via iframe.send().

You can use this method to submit the HTML form to upload a file to the IBM Content Navigator add document service.

Parameters:

serviceName

The name of the service. Refer to navigator/WEB-INF/struts.xml for a list of the services.

repositoryType

The type of content repository: od, cm, p8, ci, cmis, or undefined for common services.

params

An object containing additional parameters and request callbacks. Parameters include:

requestParams - Object containing any request parameters that should be added to the form post.
cancellable - Flag indicating if the request can be canceled.
notifyOnCancel - Flag indicating that if a cancellable request is canceled, a notification will be sent to the service, so that it can clean up and exit immediately
backgroundRequest - Flag indicating if the request should be run in the background.
requestCompleteCallback - Callback method called when the a response from the server is received.
requestFailedCallback - Callback method called when a request returns from the server with errors.

fileInputForm

The form to post. Form is an instance of FormData.

<static> ecm.model.Request.Request.invokePluginService(pluginName, pluginServiceName, pluginParams)

This static function invokes the services to launch a plug-in-provided service.

Parameters:

pluginName

The identifier of the plug-in.

pluginServiceName

The identifier of the service as defined by the plug-in.

pluginParams

An object containing additional parameters and request callbacks. Parameters include:

requestHeaders - Parameters intended for the Request Header. When requestHeaders is provided, the caller is responsible for optionally setting the "Cache-Control" request header, as a default option will not be set. When requestHeaders is not provided, "Cache-Control" "no-cache" is used.
requestParams - A simple JavaScript object with name/value parameters for the plug-in.
cancellable - Flag indicating if the request can be canceled
notifyOnCancel - Flag indicating that if a cancellable request is canceled, a notification will be sent to the service, so that it can clean up and exit immediately
backgroundRequest - Flag indicating if the request should be run in the background.
requestCompleteCallback - Callback method called when the a response from the server is received.
requestFailedCallback - Callback method called when a request returns from the server with errors.

<static> ecm.model.Request.Request.invokePluginServiceSynchronous(pluginName, pluginServiceName, pluginParams)

This static function will synchronously invoke the services to launch a plug-in-provided service. Use of this method is discouraged.A synchronous request blocks all browser operations until the request completes. Consider using an asynchronous request instead.

Parameters:

pluginName

The identifier of the plug-in.

pluginServiceName

The identifier of the service as defined by the plug-in.

pluginParams

An object containing additional parameters and request callbacks. Parameters include:

requestHeaders - Parameters intended for the Request Header. When requestHeaders is provided, the caller is responsible for optionally setting the "Cache-Control" request header, as a default option will not be set. When requestHeaders is not provided, "Cache-Control" "no-cache" is used.
requestParams - A simple JavaScript object with name/value parameters for the plug-in.
cancellable - Flag indicating if the request can be canceled
notifyOnCancel - Flag indicating that if a cancellable request is canceled, a notification will be sent to the service, so that it can clean up and exit immediately
requestCompleteCallback - Callback method called when the a response from the server is received.
requestFailedCallback - Callback method called when a request returns from the server with errors.

Returns:: The JSON parsed response of the service.

<static> ecm.model.Request.Request.invokeServiceAPI(serviceName, repositoryType, params)

This static function creates and sends a request to an IBM Content Navigator service via HTTP GET.

Parameters:

serviceName

The name of the service. Refer to navigator/WEB-INF/struts.xml for a list of the services.

repositoryType

The type of content repository: od, cm, p8, ci, cmis, or undefined for common services.

params

An object containing additional parameters and request callbacks. Parameters include:

requestHeaders - Parameters intended for the Request Header. When requestHeaders is provided, the caller is responsible for optionally setting the "Cache-Control" request header, as a default option will not be set. When requestHeaders is not provided, "Cache-Control" "no-cache" is used.
requestParams - Parameters intended for the URL (for GET requests) or request body (for POST requests).
cancellable - Flag indicating if the request can be canceled
notifyOnCancel - Flag indicating that if a cancellable request is canceled, a notification will be sent to the service, so that it can clean up and exit immediately
backgroundRequest - Flag indicating if the request should be run in the background.
synchronous - Flag indicating if this is a synchronous request. By default all requests are asynchronous. Using synchronous requests is discouraged and should be used with extreme caution.
requestCompleteCallback - Callback method called when the a response from the server is received.
requestFailedCallback - Callback method called when a request returns from the server with errors.

<static> ecm.model.Request.Request.isNativeClient()

This static function returns whether the client is the native like iOS or Android or Web based.

Returns:: flag whether the client is native or not.

<static> ecm.model.Request.Request.postFormToPluginService(pluginName, pluginServiceName, form, pluginParams)

This static function creates and sends form data to a plug-in service via HTTP POST.

You can use this method to POST a request as an HTML form (for situations where the query string would be too large for a GET request). To do so, use "application/x-www.form-urlencoded" as the contentType.

Parameters:

pluginName

The identifier of the plug-in.

pluginServiceName

The identifier of the service as defined by the plug-in.

form

The form to post. Form is an instance of FormData.

pluginParams

An object containing additional parameters and request callbacks. Parameters include:

requestHeaders - Parameters intended for the Request Header. When requestHeaders is provided, the caller is responsible for optionally setting the "Cache-Control" request header, as a default option will not be set. When requestHeaders is not provided, "Cache-Control" "no-cache" is used.
requestParams - An object with name/value pairs to add to the request URL.
cancellable - Flag indicating if the request can be canceled.
notifyOnCancel - Flag indicating that if a cancellable request is canceled, a notification will be sent to the service, so that it can clean up and exit immediately
backgroundRequest - Flag indicating if the request should be run in the background.
requestCompleteCallback - Callback method called when a response from the server is received.
requestFailedCallback - Callback method called when a request returns from the server with errors.

<static> ecm.model.Request.Request.postFormToServiceAPI(serviceName, repositoryType, params, form)

This static function creates and sends form data to an IBM Content Navigator service via HTTP POST.

Parameters:

serviceName

The name of the service. Refer to navigator/WEB-INF/struts.xml for a list of the services.

repositoryType

The type of content repository: od, cm, p8, ci, cmis, or undefined for common services.

params

An object containing additional parameters and request callbacks. Parameters include:

requestHeaders - Parameters intended for the Request Header. When requestHeaders is provided, the caller is responsible for optionally setting the "Cache-Control" request header, as a default option will not be set. When requestHeaders is not provided, "Cache-Control" "no-cache" is used.
requestParams - Object containing any request parameters that should be added to the form post.
cancellable - Flag indicating if the request can be canceled
notifyOnCancel - Flag indicating that if a cancellable request is canceled, a notification will be sent to the service, so that it can clean up and exit immediately
backgroundRequest - Flag indicating if the request should be run in the background.
requestCompleteCallback - Callback method called when the a response from the server is received.
requestFailedCallback - Callback method called when a request returns from the server with errors.

form

The form to post. Form is an instance of FormData.

<static> ecm.model.Request.Request.postPluginService(pluginName, pluginServiceName, contentType, pluginParams)

This static function will invoke the services to launch a plug-in provided service. The request is performed by using an HTTP POST.

Parameters:

pluginName

The identifier of the plug-in.

pluginServiceName

The identifier of the service as defined by the plug-in.

contentType

The MIME content type of the content to post.

pluginParams

An object containing additional parameters and request callbacks. Parameters include:

requestHeaders - Parameters intended for the Request Header. When requestHeaders is provided, the caller is responsible for optionally setting the "Cache-Control" request header, as a default option will not be set. When requestHeaders is not provided, "Cache-Control" "no-cache" is used.
requestParams - An object with name/value pairs to add to the request URL.
requestBody - An object with name/value pairs to add to the body of the request.
cancellable - Flag indicating if the request can be canceled
notifyOnCancel - Flag indicating that if a cancellable request is canceled, a notification will be sent to the service, so that it can clean up and exit immediately
backgroundRequest - Flag indicating if the request should be run in the background.
requestCompleteCallback - Callback method called when the a response from the server is received.
requestFailedCallback - Callback method called when a request returns from the server with errors.

<static> ecm.model.Request.Request.postServiceAPI(serviceName, repositoryType, contentType, params)

This static function creates and sends a request to an IBM Content Navigator service via HTTP POST.

You can use this method to POST a request as an HTML form (for situations where the query string would be too large for a GET request). To do so, use "application/x-www-form-urlencoded" as the contentType and ioQuery.objectToQuery(params) for the content. Leave the params empty.

Parameters:

serviceName

The name of the service. Refer to navigator/WEB-INF/struts.xml for a list of the services.

repositoryType

The type of content repository: od, cm, p8, ci, cmis, or undefined for common services.

contentType

The MIME content type of the content to post.

params

An object containing additional parameters and request callbacks. Parameters include:

requestHeaders - Parameters intended for the Request Header. When requestHeaders is provided, the caller is responsible for optionally setting the "Cache-Control" request header, as a default option will not be set. When requestHeaders is not provided, "Cache-Control" "no-cache" is used.
requestParams - Parameters for the POST request body.
requestBody - The request body. Could be an object or string to add to the body of the request.
cancellable - Flag indicating if the request can be canceled
notifyOnCancel - Flag indicating that if a cancellable request is canceled, a notification will be sent to the service, so that it can clean up and exit immediately
backgroundRequest - Flag indicating if the request should be run in the background.
synchronous - Flag indicating if this is a synchronous request. By default all requests are asynchronous. Using synchronous requests is discouraged and should be used with extreme caution.
requestCompleteCallback - Callback method called when the a response from the server is received.
requestFailedCallback - Callback method called when a request returns from the server with errors.

<static> ecm.model.Request.Request.postSynchronousPluginService(pluginName, pluginServiceName, contentType, pluginParams)

This static function will synchronously invoke the services to launch a plug-in provided service. The request is performed using an HTTP POST.

Parameters:

pluginName

The identifier of the plug-in.

pluginServiceName

The identifier of the service as defined by the plug-in.

contentType

The MIME content type of the content to post.

pluginParams

An object containing additional parameters and request callbacks. Parameters include:

requestHeaders - Parameters intended for the Request Header. When requestHeaders is provided, the caller is responsible for optionally setting the "Cache-Control" request header, as a default option will not be set. When requestHeaders is not provided, "Cache-Control" "no-cache" is used.
requestParams - An object with name/value pairs to add to the request URL.
requestBody - An object with name/value pairs to add to the body of the request.
cancellable - Flag indicating if the request can be canceled
notifyOnCancel - Flag indicating that if a cancellable request is canceled, a notification will be sent to the service, so that it can clean up and exit immediately
backgroundRequest - Flag indicating if the request should be run in the background.
requestCompleteCallback - Callback method called when the a response from the server is received.
requestFailedCallback - Callback method called when a request returns from the server with errors.

<static> ecm.model.Request.Request.setNativeClient(isNativeClient)

This static function set whether the client is the native like iOS or Android or Web based.

Parameters:
isNativeClient: The isNativeClient is native client flag.

<static> ecm.model.Request.Request.setSecurityToken(params)

Adds a security token to request parameters

Parameters:
params: The request parameters, either in the form of a query string, or an object.

Returns:: The resulting request parameters

responseIsHtml()

Returns true if the response Content-Type contains "text/html". This is only valid after the ready state is 4 (response received).

Since:: 2.0.2

retry()

Reruns the request. This function should be used only after a request has failed due to an error that is recoverable, such as a session expiration.

send(params)

Sends the request to the server.

Parameters:
params: The set of parameters to mix into the request object in order to send the server request.
Example: send({requestMethod: "POST", requestCompleteCallback: function() {...}});