turbocommons-ts
Version:
General purpose library that implements frequently used and generic software development tasks
278 lines (277 loc) • 15.2 kB
TypeScript
/**
* TurboCommons is a general purpose and cross-language library that implements frequently used and generic software development tasks.
*
* Website : -> https://turboframework.org/en/libs/turbocommons
* License : -> Licensed under the Apache License, Version 2.0. You may not use this file except in compliance with the License.
* License Url : -> http://www.apache.org/licenses/LICENSE-2.0
* CopyRight : -> Copyright 2015 Edertone Advanded Solutions (08211 Castellar del Vallès, Barcelona). http://www.edertone.com
*/
import { HashMapObject } from '../model/HashMapObject';
import { HTTPManagerBaseRequest } from './httpmanager/HTTPManagerBaseRequest';
/**
* Class that contains functionalities related to the HTTP protocol and its most common requests
*/
export declare class HTTPManager {
/**
* If we want to use relative urls on all the requests that are executed by this class, we can define here a root
* url. All the request urls will then be composed as baseUrl + requestUrl.
*
* This property is useful when all the requests in our application share the same root url, which can be defined here.
*/
baseUrl: string;
/**
* Defines if the http comunications made by this class will be synchronous (code execution will be stopped while
* waiting for the response) or asynchronous (execution flow will continue and response will be processed once received)
* Note: Synchronous requests are normally NOT, NOT a good idea on client side languages
*/
asynchronous: boolean;
/**
* Defines how much miliseconds will the http requests wait before failing with a timeout.
* If set to 0, no value will be specifically defined, so the platform default will be used.
*/
timeout: number;
/**
* If this flag is enabled, any request that is made by this service which uses http:// instead of https:// will throw
* an exception. When disabled, non secure http:// requests will be allowed
*/
isOnlyHttps: boolean;
/**
* Defines a list with internet urls that will be used to test network availability by the
* isInternetAvailable() method. We mainly use globally available CDN urls, cause these are
* not blocked by cross-orining policies on the browsers and are widely available and replicated.
* It may be interesting to add your own server side url at the bengining of this list, so it will
* be the first one to be tested, and you will also check that your server is correctly responding.
* Note that when an url request is successful, process ends and internet connection is considered
* to be working.
*/
internetCheckLocations: string[];
/**
* Error message that is used when a timeout happens
*/
private static ERROR_TIMEOUT;
/**
* Structure containing all the created request queues and their status
*/
private _queues;
/**
* A list of key value pairs that define post parameters that will be sent ALWAYS with all the requests that are
* performed by this class. We can use this feature for example to always send a token to web services, or other
* globally sent post values
*/
private _globalPostParams;
/**
* Class that contains functionalities related to the HTTP protocol and its most common requests
*
* @param asynchronous Specify if the HTTP manager instance will work in asynchronous or synchronous mode.
* (Synchronous mode is NOT recommended on client side languages)
*/
constructor(asynchronous?: boolean);
/**
* Set the value for a POST parameter that will be stored as a global POST parameter which will be always
* sent with all the http manager requests
*
* @param parameterName The name of the POST parameter that will be always sent to all the http requests
* @param value The value that the POST parameter will have
*/
setGlobalPostParam(parameterName: string, value: string): void;
/**
* Check if the specified parameter name is defined as a global POST parameter
*
* @param parameterName The name of the POST parameter that we want to check
*
* @return True if the parameter exists, false otherwise
*/
isGlobalPostParam(parameterName: string): boolean;
/**
* Get the value for a previously defined global POST parameter
*
* @param parameterName The name of the POST parameter that we want to read
*
* @return The parameter value
*/
getGlobalPostParam(parameterName: string): any;
/**
* Delete a previously created global POST parameter so it is not sent with all the http manager requests anymore
*
* @param parameterName The name of the POST parameter that will be deleted
*/
deleteGlobalPostParam(parameterName: string): void;
/**
* Create a new http queue. Requests can then be added to this queue with the queue() method.
*
* @param name The name we want to define for this queue
*
* @see this.queue()
*
* @returns void
*/
createQueue(name: string): void;
/**
* Get the number of created queues. Some may be running and some may be not
*
* @see this.queue()
*
* @return The number of existing queues
*/
countQueues(): number;
/**
* Check if the specified queue is currently executing http requests
*
* @param name The name for the queue we want to check
*
* @see this.queue()
*
* @return boolean True if the specified queue is actually running its http requests
*/
isQueueRunning(name: string): boolean;
/**
* Remove the specified queue from this manager.
* Make sure the queue is not running when calling this method, or an exception will happen
*
* @param name The name for the queue we want to remove
*
* @see this.queue()
*
* @return void
*/
deleteQueue(name: string): void;
/**
* This method generates a GET url query from a set of key/value pairs
*
* A query string is the part of an url that contains the GET parameters. It is placed after
* the ? symbol and contains a list of parameters and values that are sent to the url.
*
* @param keyValuePairs An object or a HashMapObject containing key/value pairs that will be used to construct the query string.
* Note that when a value is an object or array, it will be encoded as a JSON string on the resulting query
*
* @see https://en.wikipedia.org/wiki/Query_string
* @see HashMapObject
*
* @return A valid query string that can be used with any url: http://www.url.com?query_string (Note that ? symbol is not included)
*/
generateUrlQueryString(keyValuePairs: {
[key: string]: any;
} | HashMapObject): string;
/**
* Tells if there's currently a working internet connection available or not.
*
* @param yesCallback Executed if the internet connection is available and working
* @param noCallback Executed if the internet connection is NOT available
*
* @return void
*/
isInternetAvailable(yesCallback: () => void, noCallback: () => void): void;
/**
* Test if the specified url exists by trying to connect to it.
* Note that crossdomain security rules may prevent this method from working correctly if you try
* to check the existence of an url that does not allow CORS outside your application domain.
*
* @param url A full valid internet address to check
* @param yesCallback Executed if the url exists
* @param noCallback Executed if the url does not exist (or is not accessible).
*
* @return void
*/
urlExists(url: string, yesCallback: () => void, noCallback: () => void): void;
/**
* Get the Http headers for a given url.
* Note that crossdomain security rules may prevent this method from working correctly
*
* @param url The url for which we want to get the http headers.
* @param successCallback Executed when headers are read. An array of strings will be passed to this method
* containing all the read headers with each header line as an array element.
* @param errorCallback Executed if headers cannot be read. A string containing the error description and the error
* code will be passed to this method.
*
* @return void
*/
getUrlHeaders(url: string, successCallback: (headersArray: string[]) => void, errorCallback: (errorMsg: string, errorCode: number) => void): void;
/**
* Launch one or more http requests without caring about their execution order.
*
* @param requests One or more requests to be inmediately launched (at the same time if possible). Each request can be defined as a string
* that will be used as a GET request url, or as an HTTPManagerBaseRequest instance in case we want to define parameters and callbacks.
* @param finishedCallback A method to be executed once all the http requests have finished (either succesfully or with errors). The callback will
* receive two parameters: results (an array with information about each request result in the same order as provided to this method) and
* anyError (true if any of the requests has failed)
* @param progressCallback Executed after each one of the urls finishes (either successfully or with an error). A string with the requested url and
* the total requests to perform will be passed to this method.
*
* @return void
*/
execute(requests: string | string[] | HTTPManagerBaseRequest | HTTPManagerBaseRequest[], finishedCallback?: ((results: {
url: string;
response: any;
isError: boolean;
errorMsg: string;
code: number;
}[], anyError: boolean) => void) | null, progressCallback?: null | ((completedUrl: string, totalRequests: number) => void)): void;
/**
* Auxiliary method to call the send method for an XMLHttpRequest with more explanatory error checking
*
* NOTE: this method is exclusive for the typescript / javascript versions of turbocommons
*/
private _executeXmlHttprequestSend;
/**
* Auxiliary method to generate a valid list of HTTPManagerBaseRequest instances from multiple sources
*/
private _generateValidRequestsList;
/**
* Sequentially launch one or more http requests to the specified queue, one after the other.
* Each request will start inmediately after the previous one is finished (either succesfully or with an error).
* We can have several independent queues that run their requests at the same time.
*
* @param requests One or more requests that must be added to the specified queue. Each request can be defined as a string
* that will be used as a GET request url, or as an HTTPManagerBaseRequest instance in case we want to define parameters and callbacks.
* Requests will be sequentially executed one after the other in the same order. If the specified queue contains requests
* that have not finished yet, they will be executed before the ones provided here.
* @param queueName The name for an existing queue (created with this.createQueue()) where the specified requests will be added
* @param finishedAllCallback A method that will be executed once all the queued requests by this method have finished. Note that
* if the specified queue already contains running requests, the current ones will be added to be executed after and
* when all have finished, this method will be called.
*
* @returns void
*/
queue(requests: string | string[] | HTTPManagerBaseRequest | HTTPManagerBaseRequest[], queueName: string, finishedCallback?: (() => void) | null): void;
/**
* Auxiliary method that is used to begin executing the http requests that are pending on the specified queue.
* A recursive operation will be used to launch the next http request once the previous has totally finished.
*
* @param name The name for the queue we want to start
*
* @returns void
*/
private _startQueue;
/**
* Given a url with a list of resources (normally files), this method will perform a request for each one of them and
* store the whole file contents as an element of a result array. After all the process completes, the array containing all the loaded
* data will be available by the successCallback method.
*
* This is a technique that allows us to read a big list of files from an http server without needing to
* write much code. We simply put the files on the server, create a list with all the file names, provide the base url for all the files,
* and call this method. When the process succeeds, we will have all the files data loaded and ready to be used. We have also a progress callback
* that will notify us when each one of the files is correctly loaded.
*
* @param urlToListOfResources An url that gives us the list of resources to be loaded (normally a plain list of file names)
* @param baseUrl A url that will be used as the root for all the files of the list when the load is performed. This usually is the path
* to the url folder that contains the files. Each request to a file will be composed with this baseUrl + the respective entry of the file
* on urlToListOfResources
* @param successCallback Executed once all the resources have been loaded. Two parameters will be passed to this method: An array with
* The list of resources as they are defined on the urlToListOfResources, and an array containing all the data for each
* one of these resources.
* @param errorCallback Executed if a failure happens on any of the requests. The url that caused the error,
* the error description and the error code will be passed to this method.
* @param progressCallback Executed after each one of the resources is correctly loaded. A string with the correctly
* requested url will be passed to this method.
*
* @returns void
*/
loadResourcesFromList(urlToListOfResources: string, baseUrl: string, successCallback: (resourcesList: string[], resourcesData: string[]) => void, errorCallback: (errorUrl: string, errorMsg: string, errorCode: number) => void, progressCallback?: ((completedUrl: string) => void) | null): void;
/**
* Auxiliary method to join two urls: A base one, and a relative one
*
* If a full absolute url is passed to the relativeUrl variable, the result of this method will be the relative one, ignoring
* any possible value on baseUrl.
*/
private _composeUrl;
}