You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@olingo.apache.org by ko...@apache.org on 2014/08/15 09:22:44 UTC
[1/3] [OLINGO-408] first conversion of the doc comments
Repository: olingo-odata4-js
Updated Branches:
refs/heads/master 4e1a3baf6 -> facdabac5
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/odata/metadata.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/odata/metadata.js b/datajs/src/lib/odata/metadata.js
index 50057a1..582da7d 100644
--- a/datajs/src/lib/odata/metadata.js
+++ b/datajs/src/lib/odata/metadata.js
@@ -43,16 +43,15 @@ var MAX_DATA_SERVICE_VERSION = odataHandler.MAX_DATA_SERVICE_VERSION;
var xmlMediaType = "application/xml";
+/** Creates an object that describes an element in an schema.
+ * @param {Array} attributes - List containing the names of the attributes allowed for this element.
+ * @param {Array} elements - List containing the names of the child elements allowed for this element.
+ * @param {Boolean} text - Flag indicating if the element's text value is of interest or not.
+ * @param {String} ns - Namespace to which the element belongs to.
+ * If a child element name ends with * then it is understood by the schema that that child element can appear 0 or more times.
+ * @returns {Object} Object with attributes, elements, text, and ns fields.
+ */
var schemaElement = function (attributes, elements, text, ns) {
- /// <summary>Creates an object that describes an element in an schema.</summary>
- /// <param name="attributes" type="Array">List containing the names of the attributes allowed for this element.</param>
- /// <param name="elements" type="Array">List containing the names of the child elements allowed for this element.</param>
- /// <param name="text" type="Boolean">Flag indicating if the element's text value is of interest or not.</param>
- /// <param name="ns" type="String">Namespace to which the element belongs to.</param>
- /// <remarks>
- /// If a child element name ends with * then it is understood by the schema that that child element can appear 0 or more times.
- /// </remarks>
- /// <returns type="Object">Object with attributes, elements, text, and ns fields.</returns>
return {
attributes: attributes,
@@ -357,11 +356,12 @@ var schema = {
};
+/** Converts a Pascal-case identifier into a camel-case identifier.
+ * @param {String} text - Text to convert.
+ * @returns {String} Converted text.
+ * If the text starts with multiple uppercase characters, it is left as-is.</remarks>
+ */
var scriptCase = function (text) {
- /// <summary>Converts a Pascal-case identifier into a camel-case identifier.</summary>
- /// <param name="text" type="String">Text to convert.</param>
- /// <returns type="String">Converted text.</returns>
- /// <remarks>If the text starts with multiple uppercase characters, it is left as-is.</remarks>
if (!text) {
return text;
@@ -379,11 +379,12 @@ var scriptCase = function (text) {
return text.charAt(0).toLowerCase();
};
+/** Gets the schema node for the specified element.
+ * @param {Object} parentSchema - Schema of the parent XML node of 'element'.
+ * @param candidateName - XML element name to consider.
+ * @returns {Object} The schema that describes the specified element; null if not found.
+ */
var getChildSchema = function (parentSchema, candidateName) {
- /// <summary>Gets the schema node for the specified element.</summary>
- /// <param name="parentSchema" type="Object">Schema of the parent XML node of 'element'.</param>
- /// <param name="candidateName">XML element name to consider.</param>
- /// <returns type="Object">The schema that describes the specified element; null if not found.</returns>
var elements = parentSchema.elements;
if (!elements) {
@@ -408,18 +409,20 @@ var getChildSchema = function (parentSchema, candidateName) {
return null;
};
+/** Checks whether the specifies namespace URI is one of the known CSDL namespace URIs.
+ * @param {String} nsURI - Namespace URI to check.
+ * @returns {Boolean} true if nsURI is a known CSDL namespace; false otherwise.
+ */
var isEdmNamespace = function (nsURI) {
- /// <summary>Checks whether the specifies namespace URI is one of the known CSDL namespace URIs.</summary>
- /// <param name="nsURI" type="String">Namespace URI to check.</param>
- /// <returns type="Boolean">true if nsURI is a known CSDL namespace; false otherwise.</returns>
return nsURI === edmNs1;
};
+/** Parses a CSDL document.
+ * @param element - DOM element to parse.
+ * @returns {Object} An object describing the parsed element.
+ */
var parseConceptualModelElement = function (element) {
- /// <summary>Parses a CSDL document.</summary>
- /// <param name="element">DOM element to parse.</param>
- /// <returns type="Object">An object describing the parsed element.</returns>
var localName = xmlLocalName(element);
var nsURI = xmlNamespaceURI(element);
@@ -493,11 +496,12 @@ var parseConceptualModelElement = function (element) {
return item;
};
+/** Parses a metadata document.
+ * @param handler - This handler.
+ * @param {String} text - Metadata text.
+ * @returns An object representation of the conceptual model.</returns>
+ */
var metadataParser = function (handler, text) {
- /// <summary>Parses a metadata document.</summary>
- /// <param name="handler">This handler.</param>
- /// <param name="text" type="String">Metadata text.</param>
- /// <returns>An object representation of the conceptual model.</returns>
var doc = xmlParse(text);
var root = xmlFirstChildElement(doc);
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/odata/net.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/odata/net.js b/datajs/src/lib/odata/net.js
index 759d56e..655a961 100644
--- a/datajs/src/lib/odata/net.js
+++ b/datajs/src/lib/odata/net.js
@@ -25,18 +25,18 @@ var delay = utils.delay;
var ticks = 0;
+/* Checks whether the specified request can be satisfied with a JSONP request.
+ * @param request - Request object to check.
+ * @returns {Boolean} true if the request can be satisfied; false otherwise.
+
+ * Requests that 'degrade' without changing their meaning by going through JSONP
+ * are considered usable.
+ *
+ * We allow data to come in a different format, as the servers SHOULD honor the Accept
+ * request but may in practice return content with a different MIME type.
+ */
var canUseJSONP = function (request) {
- /// <summary>
- /// Checks whether the specified request can be satisfied with a JSONP request.
- /// </summary>
- /// <param name="request">Request object to check.</param>
- /// <returns type="Boolean">true if the request can be satisfied; false otherwise.</returns>
-
- // Requests that 'degrade' without changing their meaning by going through JSONP
- // are considered usable.
- //
- // We allow data to come in a different format, as the servers SHOULD honor the Accept
- // request but may in practice return content with a different MIME type.
+
if (request.method && request.method !== "GET") {
return false;
}
@@ -44,10 +44,11 @@ var canUseJSONP = function (request) {
return true;
};
+/** Creates an IFRAME tag for loading the JSONP script
+ * @param {String} url - The source URL of the script
+ * @returns {HTMLElement} The IFRAME tag
+ */
var createIFrame = function (url) {
- /// <summary>Creates an IFRAME tag for loading the JSONP script</summary>
- /// <param name="url" type="String">The source URL of the script</param>
- /// <returns type="HTMLElement">The IFRAME tag</returns>
var iframe = window.document.createElement("IFRAME");
iframe.style.display = "none";
@@ -61,9 +62,10 @@ var createIFrame = function (url) {
return iframe;
};
+/** Creates a XmlHttpRequest object.
+ * @returns {XmlHttpRequest} XmlHttpRequest object.
+ */
var createXmlHttpRequest = function () {
- /// <summary>Creates a XmlHttpRequest object.</summary>
- /// <returns type="XmlHttpRequest">XmlHttpRequest object.</returns>
if (window.XMLHttpRequest) {
return new window.XMLHttpRequest();
}
@@ -84,20 +86,21 @@ var createXmlHttpRequest = function () {
throw exception;
};
+/** Checks whether the specified URL is an absolute URL.
+ * @param {String} url - URL to check.
+ * @returns {Boolean} true if the url is an absolute URL; false otherwise.
+*/
var isAbsoluteUrl = function (url) {
- /// <summary>Checks whether the specified URL is an absolute URL.</summary>
- /// <param name="url" type="String">URL to check.</param>
- /// <returns type="Boolean">true if the url is an absolute URL; false otherwise.</returns>
-
return url.indexOf("http://") === 0 ||
url.indexOf("https://") === 0 ||
url.indexOf("file://") === 0;
};
+/** Checks whether the specified URL is local to the current context.
+ * @param {String} url - URL to check.
+ * @returns {Boolean} true if the url is a local URL; false otherwise.
+ */
var isLocalUrl = function (url) {
- /// <summary>Checks whether the specified URL is local to the current context.</summary>
- /// <param name="url" type="String">URL to check.</param>
- /// <returns type="Boolean">true if the url is a local URL; false otherwise.</returns>
if (!isAbsoluteUrl(url)) {
return true;
@@ -109,10 +112,11 @@ var isLocalUrl = function (url) {
return (url.indexOf(locationDomain) === 0);
};
+/** Removes a callback used for a JSONP request.
+ * @param {String} name - Function name to remove.
+ * @param {Number} tick - Tick count used on the callback.
+ */
var removeCallback = function (name, tick) {
- /// <summary>Removes a callback used for a JSONP request.</summary>
- /// <param name="name" type="String">Function name to remove.</param>
- /// <param name="tick" type="Number">Tick count used on the callback.</param>
try {
delete window[name];
} catch (err) {
@@ -123,10 +127,11 @@ var removeCallback = function (name, tick) {
}
};
+/** Removes an iframe.
+ * @param {Object} iframe - The iframe to remove.
+ * @returns {Object} Null value to be assigned to iframe reference.
+ */
var removeIFrame = function (iframe) {
- /// <summary>Removes an iframe.</summary>
- /// <param name="iframe" type="Object">The iframe to remove.</param>
- /// <returns type="Object">Null value to be assigned to iframe reference.</returns>
if (iframe) {
writeHtmlToIFrame(iframe, "");
iframe.parentNode.removeChild(iframe);
@@ -135,10 +140,11 @@ var removeIFrame = function (iframe) {
return null;
};
+/** Reads response headers into array.
+ * @param {XMLHttpRequest} xhr - HTTP request with response available.
+ * @param {Array} headers - Target array to fill with name/value pairs.
+ */
var readResponseHeaders = function (xhr, headers) {
- /// <summary>Reads response headers into array.</summary>
- /// <param name="xhr" type="XMLHttpRequest">HTTP request with response available.</param>
- /// <param name="headers" type="Array">Target array to fill with name/value pairs.</param>
var responseHeaders = xhr.getAllResponseHeaders().split(/\r?\n/);
var i, len;
@@ -150,10 +156,11 @@ var readResponseHeaders = function (xhr, headers) {
}
};
+/** Writes HTML to an IFRAME document.
+ * @param {HTMLElement} iframe - The IFRAME element to write to.
+ * @param {String} html - The HTML to write.
+ */
var writeHtmlToIFrame = function (iframe, html) {
- /// <summary>Writes HTML to an IFRAME document.</summary>
- /// <param name="iframe" type="HTMLElement">The IFRAME element to write to.</param>
- /// <param name="html" type="String">The HTML to write.</param>
var frameDocument = (iframe.contentWindow) ? iframe.contentWindow.document : iframe.contentDocument.document;
frameDocument.open();
frameDocument.write(html);
@@ -167,12 +174,13 @@ exports.defaultHttpClient = {
enableJsonpCallback: false,
+ /** Performs a network request.
+ * @param {Object} request - Request description
+ * @param {Function} success - Success callback with the response object.
+ * @param {Function} error - Error callback with an error object.
+ * @returns {Object} Object with an 'abort' method for the operation.
+ */
request: function (request, success, error) {
- /// <summary>Performs a network request.</summary>
- /// <param name="request" type="Object">Request description.</request>
- /// <param name="success" type="Function">Success callback with the response object.</param>
- /// <param name="error" type="Function">Error callback with an error object.</param>
- /// <returns type="Object">Object with an 'abort' method for the operation.</returns>
var result = {};
var xhr = null;
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/odata/utils.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/odata/utils.js b/datajs/src/lib/odata/utils.js
index b42e57e..01f59c2 100644
--- a/datajs/src/lib/odata/utils.js
+++ b/datajs/src/lib/odata/utils.js
@@ -165,13 +165,13 @@ var geographyTypes = [
GEOGRAPHY_MULTIPOINT
];
+/** Invokes a function once per schema in metadata.
+ * @param metadata - Metadata store; one of edmx, schema, or an array of any of them.
+ * @param {Function} callback - Callback function to invoke once per schema.
+ * @returns The first truthy value to be returned from the callback; null or the last falsy value otherwise.
+ */
var forEachSchema = function (metadata, callback) {
- /// <summary>Invokes a function once per schema in metadata.</summary>
- /// <param name="metadata">Metadata store; one of edmx, schema, or an array of any of them.</param>
- /// <param name="callback" type="Function">Callback function to invoke once per schema.</param>
- /// <returns>
- /// The first truthy value to be returned from the callback; null or the last falsy value otherwise.
- /// </returns>
+
if (!metadata) {
return null;
@@ -196,12 +196,13 @@ var forEachSchema = function (metadata, callback) {
}
};
+/** Formats a millisecond and a nanosecond value into a single string.
+ * @param {Numaber} ms - Number of milliseconds to format.</param>
+ * @param {Numaber} ns - Number of nanoseconds to format.</param>
+ * @returns {String} Formatted text.
+ * If the value is already as string it's returned as-is.</remarks>
+ */
var formatMilliseconds = function (ms, ns) {
- /// <summary>Formats a millisecond and a nanosecond value into a single string.</summary>
- /// <param name="ms" type="Number" mayBeNull="false">Number of milliseconds to format.</param>
- /// <param name="ns" type="Number" mayBeNull="false">Number of nanoseconds to format.</param>
- /// <returns type="String">Formatted text.</returns>
- /// <remarks>If the value is already as string it's returned as-is.</remarks>
// Avoid generating milliseconds if not necessary.
if (ms === 0) {
@@ -222,11 +223,12 @@ var formatDateTimeOffsetJSON = function (value) {
return "\/Date(" + value.getTime() + ")\/";
};
+/** Formats a DateTime or DateTimeOffset value a string.
+ * @param {Date} value - Value to format
+ * @returns {String} Formatted text.
+ * If the value is already as string it's returned as-is
+ยด*/
var formatDateTimeOffset = function (value) {
- /// <summary>Formats a DateTime or DateTimeOffset value a string.</summary>
- /// <param name="value" type="Date" mayBeNull="false">Value to format.</param>
- /// <returns type="String">Formatted text.</returns>
- /// <remarks>If the value is already as string it's returned as-is.</remarks>
if (typeof value === "string") {
return value;
@@ -268,10 +270,11 @@ var formatDateTimeOffset = function (value) {
ms + offset;
};
+/** Converts a duration to a string in xsd:duration format.
+ * @param {Object} value - Object with ms and __edmType properties.
+ * @returns {String} String representation of the time object in xsd:duration format.
+ */
var formatDuration = function (value) {
- /// <summary>Converts a duration to a string in xsd:duration format.</summary>
- /// <param name="value" type="Object">Object with ms and __edmType properties.</param>
- /// <returns type="String">String representation of the time object in xsd:duration format.</returns>
var ms = value.ms;
@@ -298,12 +301,13 @@ var formatDuration = function (value) {
formatMilliseconds(ms, value.ns) + "S";
};
+/** Formats the specified value to the given width.
+ * @param {Number} value - Number to format (non-negative).
+ * @param {Number} width - Minimum width for number.
+ * @param {Boolean} append - Flag indicating if the value is padded at the beginning (false) or at the end (true).
+ * @returns {String} Text representation.
+ */
var formatNumberWidth = function (value, width, append) {
- /// <summary>Formats the specified value to the given width.</summary>
- /// <param name="value" type="Number">Number to format (non-negative).</param>
- /// <param name="width" type="Number">Minimum width for number.</param>
- /// <param name="append" type="Boolean">Flag indicating if the value is padded at the beginning (false) or at the end (true).</param>
- /// <returns type="String">Text representation.</returns>
var result = value.toString(10);
while (result.length < width) {
if (append) {
@@ -316,18 +320,20 @@ var formatNumberWidth = function (value, width, append) {
return result;
};
+/** Gets the canonical timezone representation.
+ * @param {String} timezone - Timezone representation.
+ * @returns {String} An 'Z' string if the timezone is absent or 0; the timezone otherwise.
+ */
var getCanonicalTimezone = function (timezone) {
- /// <summary>Gets the canonical timezone representation.</summary>
- /// <param name="timezone" type="String">Timezone representation.</param>
- /// <returns type="String">An 'Z' string if the timezone is absent or 0; the timezone otherwise.</returns>
return (!timezone || timezone === "Z" || timezone === "+00:00" || timezone === "-00:00") ? "Z" : timezone;
};
+/** Gets the type of a collection type name.
+ * @param {String} typeName - Type name of the collection.
+ * @returns {String} Type of the collection; null if the type name is not a collection type.
+ */
var getCollectionType = function (typeName) {
- /// <summary>Gets the type of a collection type name.</summary>
- /// <param name="typeName" type="String">Type name of the collection.</param>
- /// <returns type="String">Type of the collection; null if the type name is not a collection type.</returns>
if (typeof typeName === "string") {
var end = typeName.indexOf(")", 10);
@@ -338,14 +344,15 @@ var getCollectionType = function (typeName) {
return null;
};
+/** Sends a request containing OData payload to a server.
+* @param request - Object that represents the request to be sent..
+* @param success - Callback for a successful read operation.
+* @param error - Callback for handling errors.
+* @param handler - Handler for data serialization.
+* @param httpClient - HTTP client layer.
+* @param context - Context used for processing the request
+*/
var invokeRequest = function (request, success, error, handler, httpClient, context) {
- /// <summary>Sends a request containing OData payload to a server.</summary>
- /// <param name="request">Object that represents the request to be sent..</param>
- /// <param name="success">Callback for a successful read operation.</param>
- /// <param name="error">Callback for handling errors.</param>
- /// <param name="handler">Handler for data serialization.</param>
- /// <param name="httpClient">HTTP client layer.</param>
- /// <param name="context">Context used for processing the request</param>
return httpClient.request(request, function (response) {
try {
@@ -376,10 +383,11 @@ var invokeRequest = function (request, success, error, handler, httpClient, cont
}, error);
};
+/** Tests whether a value is a batch object in the library's internal representation.
+ * @param value - Value to test.
+ * @returns {Boolean} True is the value is a batch object; false otherwise.
+ */
var isBatch = function (value) {
- /// <summary>Tests whether a value is a batch object in the library's internal representation.</summary>
- /// <param name="value">Value to test.</param>
- /// <returns type="Boolean">True is the value is a batch object; false otherwise.</returns>
return isComplex(value) && isArray(value.__batchRequests);
};
@@ -387,11 +395,12 @@ var isBatch = function (value) {
// Regular expression used for testing and parsing for a collection type.
var collectionTypeRE = /Collection\((.*)\)/;
+/** Tests whether a value is a collection value in the library's internal representation.
+ * @param value - Value to test.
+ * @param {Sting} typeName - Type name of the value. This is used to disambiguate from a collection property value.
+ * @returns {Boolean} True is the value is a feed value; false otherwise.
+ */
var isCollection = function (value, typeName) {
- /// <summary>Tests whether a value is a collection value in the library's internal representation.</summary>
- /// <param name="value">Value to test.</param>
- /// <param name="typeName" type="Sting">Type name of the value. This is used to disambiguate from a collection property value.</param>
- /// <returns type="Boolean">True is the value is a feed value; false otherwise.</returns>
var colData = value && value.results || value;
return !!colData &&
@@ -399,17 +408,19 @@ var isCollection = function (value, typeName) {
(!typeName && isArray(colData) && !isComplex(colData[0]));
};
+/** Checks whether the specified type name is a collection type.
+ * @param {String} typeName - Name of type to check.
+ * @returns {Boolean} True if the type is the name of a collection type; false otherwise.
+ */
var isCollectionType = function (typeName) {
- /// <summary>Checks whether the specified type name is a collection type.</summary>
- /// <param name="typeName" type="String">Name of type to check.</param>
- /// <returns type="Boolean">True if the type is the name of a collection type; false otherwise.</returns>
return collectionTypeRE.test(typeName);
};
+/** Tests whether a value is a complex type value in the library's internal representation.
+ * @param value - Value to test.
+ * @returns {Boolean} True is the value is a complex type value; false otherwise.
+ */
var isComplex = function (value) {
- /// <summary>Tests whether a value is a complex type value in the library's internal representation.</summary>
- /// <param name="value">Value to test.</param>
- /// <returns type="Boolean">True is the value is a complex type value; false otherwise.</returns>
return !!value &&
isObject(value) &&
@@ -417,17 +428,19 @@ var isComplex = function (value) {
!isDate(value);
};
+/** Checks whether a Date object is DateTimeOffset value
+ * @param {Date} value - Value to check
+ * @returns {Boolean} true if the value is a DateTimeOffset, false otherwise.
+ */
var isDateTimeOffset = function (value) {
- /// <summary>Checks whether a Date object is DateTimeOffset value</summary>
- /// <param name="value" type="Date" mayBeNull="false">Value to check.</param>
- /// <returns type="Boolean">true if the value is a DateTimeOffset, false otherwise.</returns>
return (value.__edmType === "Edm.DateTimeOffset" || (!value.__edmType && value.__offset));
};
+/** Tests whether a value is a deferred navigation property in the library's internal representation.
+ * @param value - Value to test.
+ * @returns {Boolean} True is the value is a deferred navigation property; false otherwise.
+ */
var isDeferred = function (value) {
- /// <summary>Tests whether a value is a deferred navigation property in the library's internal representation.</summary>
- /// <param name="value">Value to test.</param>
- /// <returns type="Boolean">True is the value is a deferred navigation property; false otherwise.</returns>
if (!value && !isComplex(value)) {
return false;
@@ -437,19 +450,21 @@ var isDeferred = function (value) {
return !metadata.type && !!deferred.uri;
};
+/** Tests whether a value is an entry object in the library's internal representation.
+ * @param value - Value to test.
+ * @returns {Boolean} True is the value is an entry object; false otherwise.
+ */
var isEntry = function (value) {
- /// <summary>Tests whether a value is an entry object in the library's internal representation.</summary>
- /// <param name="value">Value to test.</param>
- /// <returns type="Boolean">True is the value is an entry object; false otherwise.</returns>
return isComplex(value) && value.__metadata && "uri" in value.__metadata;
};
+/** Tests whether a value is a feed value in the library's internal representation.
+ * @param value - Value to test.
+ * @param {Sting} typeName - Type name of the value. This is used to disambiguate from a collection property value.
+ * @returns {Boolean} True is the value is a feed value; false otherwise.
+ */
var isFeed = function (value, typeName) {
- /// <summary>Tests whether a value is a feed value in the library's internal representation.</summary>
- /// <param name="value">Value to test.</param>
- /// <param name="typeName" type="Sting">Type name of the value. This is used to disambiguate from a collection property value.</param>
- /// <returns type="Boolean">True is the value is a feed value; false otherwise.</returns>
var feedData = value && value.results || value;
return isArray(feedData) && (
@@ -458,10 +473,11 @@ var isFeed = function (value, typeName) {
);
};
+/** Checks whether the specified type name is a geography EDM type.
+ * @param {String} typeName - Name of type to check.
+ * @returns {Boolean} True if the type is a geography EDM type; false otherwise.
+ */
var isGeographyEdmType = function (typeName) {
- /// <summary>Checks whether the specified type name is a geography EDM type.</summary>
- /// <param name="typeName" type="String">Name of type to check.</param>
- /// <returns type="Boolean">True if the type is a geography EDM type; false otherwise.</returns>
//check with edm
var ret = contains(geographyEdmTypes, typeName) ||
@@ -470,20 +486,22 @@ var isGeographyEdmType = function (typeName) {
};
+/** Checks whether the specified type name is a geometry EDM type.
+ * @param {String} typeName - Name of type to check.
+ * @returns {Boolean} True if the type is a geometry EDM type; false otherwise.
+ */
var isGeometryEdmType = function (typeName) {
- /// <summary>Checks whether the specified type name is a geometry EDM type.</summary>
- /// <param name="typeName" type="String">Name of type to check.</param>
- /// <returns type="Boolean">True if the type is a geometry EDM type; false otherwise.</returns>
var ret = contains(geometryEdmTypes, typeName) ||
(typeName.indexOf('.') === -1 && contains(geometryTypes, typeName));
return ret;
};
+/** Tests whether a value is a named stream value in the library's internal representation.
+ * @param value - Value to test.
+ * @returns {Boolean} True is the value is a named stream; false otherwise.
+ */
var isNamedStream = function (value) {
- /// <summary>Tests whether a value is a named stream value in the library's internal representation.</summary>
- /// <param name="value">Value to test.</param>
- /// <returns type="Boolean">True is the value is a named stream; false otherwise.</returns>
if (!value && !isComplex(value)) {
return false;
@@ -493,13 +511,12 @@ var isNamedStream = function (value) {
return !metadata && !!mediaResource && !!mediaResource.media_src;
};
+/** Tests whether a value is a primitive type value in the library's internal representation.
+ * @param value - Value to test.
+ * @returns {Boolean} True is the value is a primitive type value.
+ * Date objects are considered primitive types by the library.
+ */
var isPrimitive = function (value) {
- /// <summary>Tests whether a value is a primitive type value in the library's internal representation.</summary>
- /// <param name="value">Value to test.</param>
- /// <remarks>
- /// Date objects are considered primitive types by the library.
- /// </remarks>
- /// <returns type="Boolean">True is the value is a primitive type value.</returns>
return isDate(value) ||
typeof value === "string" ||
@@ -507,24 +524,21 @@ var isPrimitive = function (value) {
typeof value === "boolean";
};
+/** Checks whether the specified type name is a primitive EDM type.
+ * @param {String} typeName - Name of type to check.
+ * @returns {Boolean} True if the type is a primitive EDM type; false otherwise.
+ */
var isPrimitiveEdmType = function (typeName) {
- /// <summary>Checks whether the specified type name is a primitive EDM type.</summary>
- /// <param name="typeName" type="String">Name of type to check.</param>
- /// <returns type="Boolean">True if the type is a primitive EDM type; false otherwise.</returns>
return contains(primitiveEdmTypes, typeName);
};
+/** Gets the kind of a navigation property value.
+ * @param value - Value of the navigation property.
+ * @param {Object} [propertyModel] - Object that describes the navigation property in an OData conceptual schema.
+ * @returns {String} String value describing the kind of the navigation property; null if the kind cannot be determined.
+ */
var navigationPropertyKind = function (value, propertyModel) {
- /// <summary>Gets the kind of a navigation property value.</summary>
- /// <param name="value">Value of the navigation property.</param>
- /// <param name="propertyModel" type="Object" optional="true">
- /// Object that describes the navigation property in an OData conceptual schema.
- /// </param>
- /// <remarks>
- /// The returned string is as follows
- /// </remarks>
- /// <returns type="String">String value describing the kind of the navigation property; null if the kind cannot be determined.</returns>
if (isDeferred(value)) {
return "deferred";
@@ -544,75 +558,82 @@ var navigationPropertyKind = function (value, propertyModel) {
return null;
};
+/** Looks up a property by name.
+ * @param {Array} properties - Array of property objects as per EDM metadata (may be null)
+ * @param {String} name - Name to look for.
+ * @returns {Object} The property object; null if not found.
+ */
var lookupProperty = function (properties, name) {
- /// <summary>Looks up a property by name.</summary>
- /// <param name="properties" type="Array" mayBeNull="true">Array of property objects as per EDM metadata.</param>
- /// <param name="name" type="String">Name to look for.</param>
- /// <returns type="Object">The property object; null if not found.</returns>
return find(properties, function (property) {
return property.name === name;
});
};
+/** Looks up a type object by name.
+ * @param {String} name - Name, possibly null or empty.
+ * @param metadata - Metadata store; one of edmx, schema, or an array of any of them.
+ * @param {String} kind - Kind of object to look for as per EDM metadata.
+ * @returns An type description if the name is found; null otherwise
+ */
var lookupInMetadata = function (name, metadata, kind) {
- /// <summary>Looks up a type object by name.</summary>
- /// <param name="name" type="String">Name, possibly null or empty.</param>
- /// <param name="metadata">Metadata store; one of edmx, schema, or an array of any of them.</param>
- /// <param name="kind" type="String">Kind of object to look for as per EDM metadata.</param>
- /// <returns>An type description if the name is found; null otherwise.</returns>
return (name) ? forEachSchema(metadata, function (schema) {
return lookupInSchema(name, schema, kind);
}) : null;
};
+/** Looks up a entity set by name.
+ * @param {Array} properties - Array of entity set objects as per EDM metadata( may be null)
+ * @param {String} name - Name to look for.
+ * @returns {Object} The entity set object; null if not found.
+ */
var lookupEntitySet = function (entitySets, name) {
- /// <summary>Looks up a entity set by name.</summary>
- /// <param name="properties" type="Array" mayBeNull="true">Array of entity set objects as per EDM metadata.</param>
- /// <param name="name" type="String">Name to look for.</param>
- /// <returns type="Object">The entity set object; null if not found.</returns>
return find(entitySets, function (entitySet) {
return entitySet.name === name;
});
};
+/** Looks up a entity set by name.
+ * @param {Array} properties - Array of entity set objects as per EDM metadata (may be null)
+ * @param {String} name - Name to look for.
+ * @returns {Object} The entity set object; null if not found.
+ */
var lookupSingleton = function (singletons, name) {
- /// <summary>Looks up a entity set by name.</summary>
- /// <param name="properties" type="Array" mayBeNull="true">Array of entity set objects as per EDM metadata.</param>
- /// <param name="name" type="String">Name to look for.</param>
- /// <returns type="Object">The entity set object; null if not found.</returns>
return find(singletons, function (singleton) {
return singleton.name === name;
});
};
+/** Looks up a complex type object by name.
+ * @param {String} name - Name, possibly null or empty.
+ * @param metadata - Metadata store; one of edmx, schema, or an array of any of them.
+ * @returns A complex type description if the name is found; null otherwise.</returns>
+ */
var lookupComplexType = function (name, metadata) {
- /// <summary>Looks up a complex type object by name.</summary>
- /// <param name="name" type="String">Name, possibly null or empty.</param>
- /// <param name="metadata">Metadata store; one of edmx, schema, or an array of any of them.</param>
- /// <returns>A complex type description if the name is found; null otherwise.</returns>
return lookupInMetadata(name, metadata, "complexType");
};
+/** Looks up an entity type object by name.
+ * @param {String} name - Name, possibly null or empty.
+ * @param metadata - Metadata store; one of edmx, schema, or an array of any of them.
+ * @returns An entity type description if the name is found; null otherwise.</returns>
+ */
var lookupEntityType = function (name, metadata) {
- /// <summary>Looks up an entity type object by name.</summary>
- /// <param name="name" type="String">Name, possibly null or empty.</param>
- /// <param name="metadata">Metadata store; one of edmx, schema, or an array of any of them.</param>
- /// <returns>An entity type description if the name is found; null otherwise.</returns>
return lookupInMetadata(name, metadata, "entityType");
};
+/** Looks up an
+ * @param {String} name - Name, possibly null or empty.
+ * @param metadata - Metadata store; one of edmx, schema, or an array of any of them.
+ * @returns An entity container description if the name is found; null otherwise.</returns>
+ */
var lookupDefaultEntityContainer = function (metadata) {
- /// <summary>Looks up an</summary>
- /// <param name="name" type="String">Name, possibly null or empty.</param>
- /// <param name="metadata">Metadata store; one of edmx, schema, or an array of any of them.</param>
- /// <returns>An entity container description if the name is found; null otherwise.</returns>
return forEachSchema(metadata, function (schema) {
if (isObject(schema.entityContainer)) {
@@ -621,31 +642,33 @@ var lookupDefaultEntityContainer = function (metadata) {
});
};
+/** Looks up an entity container object by name.
+ * @param {String} name - Name, possibly null or empty.
+ * @param metadata - Metadata store; one of edmx, schema, or an array of any of them.
+ * @returns An entity container description if the name is found; null otherwise.</returns>
+ */
var lookupEntityContainer = function (name, metadata) {
- /// <summary>Looks up an entity container object by name.</summary>
- /// <param name="name" type="String">Name, possibly null or empty.</param>
- /// <param name="metadata">Metadata store; one of edmx, schema, or an array of any of them.</param>
- /// <returns>An entity container description if the name is found; null otherwise.</returns>
return lookupInMetadata(name, metadata, "entityContainer");
};
+/** Looks up a function import by name.
+ * @param {Array} properties - Array of function import objects as per EDM metadata (May be null)
+ * @param {String} name - Name to look for.
+ * @returns {Object} The entity set object; null if not found.
+ */
var lookupFunctionImport = function (functionImports, name) {
- /// <summary>Looks up a function import by name.</summary>
- /// <param name="properties" type="Array" mayBeNull="true">Array of function import objects as per EDM metadata.</param>
- /// <param name="name" type="String">Name to look for.</param>
- /// <returns type="Object">The entity set object; null if not found.</returns>
-
return find(functionImports, function (functionImport) {
return functionImport.name === name;
});
};
+/** Looks up the target entity type for a navigation property.
+ * @param {Object} navigationProperty -
+ * @param {Object} metadata -
+ * @returns {String} The entity type name for the specified property, null if not found.
+ */
var lookupNavigationPropertyType = function (navigationProperty, metadata) {
- /// <summary>Looks up the target entity type for a navigation property.</summary>
- /// <param name="navigationProperty" type="Object"></param>
- /// <param name="metadata" type="Object"></param>
- /// <returns type="String">The entity type name for the specified property, null if not found.</returns>
var result = null;
if (navigationProperty) {
@@ -677,11 +700,12 @@ var lookupNavigationPropertyType = function (navigationProperty, metadata) {
return result;
};
+/** Looks up the target entityset name for a navigation property.
+ * @param {Object} navigationProperty -
+ * @param {Object} metadata -
+ * @returns {String} The entityset name for the specified property, null if not found.
+ */
var lookupNavigationPropertyEntitySet = function (navigationProperty, sourceEntitySetName, metadata) {
- /// <summary>Looks up the target entityset name for a navigation property.</summary>
- /// <param name="navigationProperty" type="Object"></param>
- /// <param name="metadata" type="Object"></param>
- /// <returns type="String">The entityset name for the specified property, null if not found.</returns>
if (navigationProperty) {
var rel = navigationProperty.relationship;
@@ -706,11 +730,12 @@ var lookupNavigationPropertyEntitySet = function (navigationProperty, sourceEnti
return null;
};
+/** Gets the entitySet info, container name and functionImports for an entitySet
+ * @param {Object} navigationProperty -
+ * @param {Object} metadata -
+ * @returns {Object} The info about the entitySet.
+ */
var getEntitySetInfo = function (entitySetName, metadata) {
- /// <summary>Gets the entitySet info, container name and functionImports for an entitySet</summary>
- /// <param name="navigationProperty" type="Object"></param>
- /// <param name="metadata" type="Object"></param>
- /// <returns type="Object">The info about the entitySet.</returns>
var info = forEachSchema(metadata, function (schema) {
var container = schema.entityContainer;
@@ -728,11 +753,12 @@ var getEntitySetInfo = function (entitySetName, metadata) {
return info;
};
+/** Given an expected namespace prefix, removes it from a full name.
+ * @param {String} ns - Expected namespace.
+ * @param {String} fullName - Full name in 'ns'.'name' form.
+ * @returns {String} The local name, null if it isn't found in the expected namespace.
+ */
var removeNamespace = function (ns, fullName) {
- /// <summary>Given an expected namespace prefix, removes it from a full name.</summary>
- /// <param name="ns" type="String">Expected namespace.</param>
- /// <param name="fullName" type="String">Full name in 'ns'.'name' form.</param>
- /// <returns type="String">The local name, null if it isn't found in the expected namespace.</returns>
if (fullName.indexOf(ns) === 0 && fullName.charAt(ns.length) === ".") {
return fullName.substr(ns.length + 1);
@@ -741,12 +767,13 @@ var removeNamespace = function (ns, fullName) {
return null;
};
+/** Looks up a schema object by name.
+ * @param {String} name - Name (assigned).
+ * @param schema - Schema object as per EDM metadata.
+ * @param {String} kind - Kind of object to look for as per EDM metadata.
+ * @returns An entity type description if the name is found; null otherwise.</returns>
+ */
var lookupInSchema = function (name, schema, kind) {
- /// <summary>Looks up a schema object by name.</summary>
- /// <param name="name" type="String">Name (assigned).</param>
- /// <param name="schema">Schema object as per EDM metadata.</param>
- /// <param name="kind" type="String">Kind of object to look for as per EDM metadata.</param>
- /// <returns>An entity type description if the name is found; null otherwise.</returns>
if (name && schema) {
// The name should be the namespace qualified name in 'ns'.'type' format.
@@ -760,11 +787,12 @@ var lookupInSchema = function (name, schema, kind) {
return null;
};
+/** Compares to version strings and returns the higher one.
+ * @param {String} left - Version string in the form "major.minor.rev"
+ * @param {String} right - Version string in the form "major.minor.rev"
+ * @returns {String} The higher version string.
+ */
var maxVersion = function (left, right) {
- /// <summary>Compares to version strings and returns the higher one.</summary>
- /// <param name="left" type="String">Version string in the form "major.minor.rev"</param>
- /// <param name="right" type="String">Version string in the form "major.minor.rev"</param>
- /// <returns type="String">The higher version string.</returns>
if (left === right) {
return left;
@@ -815,9 +843,10 @@ var normalHeaders = {
"retry-after": "Retry-After"
};
+/** Normalizes headers so they can be found with consistent casing.
+ * @param {Object} headers - Dictionary of name/value pairs.
+ */
var normalizeHeaders = function (headers) {
- /// <summary>Normalizes headers so they can be found with consistent casing.</summary>
- /// <param name="headers" type="Object">Dictionary of name/value pairs.</param>
for (var name in headers) {
var lowerName = name.toLowerCase();
@@ -830,10 +859,11 @@ var normalizeHeaders = function (headers) {
}
};
+/** Parses a string into a boolean value.
+ * @param propertyValue - Value to parse.
+ * @returns {Boolean} true if the property value is 'true'; false otherwise.
+ */
var parseBool = function (propertyValue) {
- /// <summary>Parses a string into a boolean value.</summary>
- /// <param name="propertyValue">Value to parse.</param>
- /// <returns type="Boolean">true if the property value is 'true'; false otherwise.</returns>
if (typeof propertyValue === "boolean") {
return propertyValue;
@@ -851,11 +881,12 @@ var parseBool = function (propertyValue) {
// 8 - everything else (presumably offset information)
var parseDateTimeRE = /^(-?\d{4,})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d+))?(.*)$/;
+/** Parses a string into a DateTime value.
+ * @param {String} value - Value to parse.
+ * @param {Boolean} withOffset - Whether offset is expected.
+ * @returns {Date} The parsed value.
+ */
var parseDateTimeMaybeOffset = function (value, withOffset, nullOnError) {
- /// <summary>Parses a string into a DateTime value.</summary>
- /// <param name="value" type="String">Value to parse.</param>
- /// <param name="withOffset" type="Boolean">Whether offset is expected.</param>
- /// <returns type="Date">The parsed value.</returns>
// We cannot parse this in cases of failure to match or if offset information is specified.
var parts = parseDateTimeRE.exec(value);
@@ -935,10 +966,11 @@ var parseDateTimeMaybeOffset = function (value, withOffset, nullOnError) {
return result;
};
+/** Parses a string into a Date object.
+ * @param {String} propertyValue - Value to parse.
+ * @returns {Date} The parsed with year, month, day set, time values are set to 0
+ */
var parseDate = function (propertyValue, nullOnError) {
- /// <summary>Parses a string into a Date object.</summary>
- /// <param name="propertyValue" type="String">Value to parse.</param>
- /// <returns type="Date">The parsed with year, month, day set, time values are set to 0</returns>
var parts = propertyValue.split('-');
if (parts.length != 3 && nullOnError) {
@@ -967,16 +999,18 @@ var parseTimeOfDay = function (propertyValue, nullOnError) {
};
};
+/** Parses a string into a DateTimeOffset value.
+ * @param {String} propertyValue - Value to parse.
+ * @returns {Date} The parsed value.
+
+
+ * The resulting object is annotated with an __edmType property and
+ * an __offset property reflecting the original intended offset of
+ * the value. The time is adjusted for UTC time, as the current
+ * timezone-aware Date APIs will only work with the local timezone.
+ */
var parseDateTimeOffset = function (propertyValue, nullOnError) {
- /// <summary>Parses a string into a DateTimeOffset value.</summary>
- /// <param name="propertyValue" type="String">Value to parse.</param>
- /// <returns type="Date">The parsed value.</returns>
- /// <remarks>
- /// The resulting object is annotated with an __edmType property and
- /// an __offset property reflecting the original intended offset of
- /// the value. The time is adjusted for UTC time, as the current
- /// timezone-aware Date APIs will only work with the local timezone.
- /// </remarks>
+
return parseDateTimeMaybeOffset(propertyValue, true, nullOnError);
};
@@ -993,13 +1027,14 @@ var isEdmDurationValue = function(value) {
parseTimeRE.test(value);
};
+/** Parses a string in xsd:duration format.
+ * @param {String} duration - Duration value.
+
+ * This method will throw an exception if the input string has a year or a month component.
+
+ * @returns {Object} Object representing the time
+ */
var parseDuration = function (duration) {
- /// <summary>Parses a string in xsd:duration format.</summary>
- /// <param name="duration" type="String">Duration value.</param>
- /// <remarks>
- /// This method will throw an exception if the input string has a year or a month component.
- /// </remarks>
- /// <returns type="Object">Object representing the time</returns>
var parts = parseTimeRE.exec(duration);
@@ -1048,13 +1083,11 @@ var parseDuration = function (duration) {
return result;
};
+/** Parses a timezone description in (+|-)nn:nn format.
+ * @param {String} timezone - Timezone offset.
+ * @returns {Object} An object with a (d)irection property of 1 for + and -1 for -, offset (h)ours and offset (m)inutes.
+ */
var parseTimezone = function (timezone) {
- /// <summary>Parses a timezone description in (+|-)nn:nn format.</summary>
- /// <param name="timezone" type="String">Timezone offset.</param>
- /// <returns type="Object">
- /// An object with a (d)irection property of 1 for + and -1 for -,
- /// offset (h)ours and offset (m)inutes.
- /// </returns>
var direction = timezone.substring(0, 1);
direction = (direction === "+") ? 1 : -1;
@@ -1064,11 +1097,12 @@ var parseTimezone = function (timezone) {
return { d: direction, h: offsetHours, m: offsetMinutes };
};
+/** Prepares a request object so that it can be sent through the network.
+* @param request - Object that represents the request to be sent.
+* @param handler - Handler for data serialization
+* @param context - Context used for preparing the request
+*/
var prepareRequest = function (request, handler, context) {
- /// <summary>Prepares a request object so that it can be sent through the network.</summary>
- /// <param name="request">Object that represents the request to be sent.</param>
- /// <param name="handler">Handler for data serialization</param>
- /// <param name="context">Context used for preparing the request</param>
// Default to GET if no method has been specified.
if (!request.method) {
@@ -1099,14 +1133,13 @@ var prepareRequest = function (request, handler, context) {
};
+/** Traverses a tree of objects invoking callback for every value.
+ * @param {Object} item - Object or array to traverse.
+ * @param {Function} callback - Callback function with key and value, similar to JSON.parse reviver.
+ * @returns {Object} The object with traversed properties.
+ Unlike the JSON reviver, this won't delete null members.</remarks>
+*/
var traverseInternal = function (item, owner, callback) {
- /// <summary>Traverses a tree of objects invoking callback for every value.</summary>
- /// <param name="item" type="Object">Object or array to traverse.</param>
- /// <param name="callback" type="Function">
- /// Callback function with key and value, similar to JSON.parse reviver.
- /// </param>
- /// <returns type="Object">The object with traversed properties.</returns>
- /// <remarks>Unlike the JSON reviver, this won't delete null members.</remarks>
if (item && typeof item === "object") {
for (var name in item) {
@@ -1126,14 +1159,13 @@ var traverseInternal = function (item, owner, callback) {
return item;
};
+/** Traverses a tree of objects invoking callback for every value.
+ * @param {Object} item - Object or array to traverse.
+ * @param {Function} callback - Callback function with key and value, similar to JSON.parse reviver.
+ * @returns {Object} The traversed object.
+ * Unlike the JSON reviver, this won't delete null members.</remarks>
+*/
var traverse = function (item, callback) {
- /// <summary>Traverses a tree of objects invoking callback for every value.</summary>
- /// <param name="item" type="Object">Object or array to traverse.</param>
- /// <param name="callback" type="Function">
- /// Callback function with key and value, similar to JSON.parse reviver.
- /// </param>
- /// <returns type="Object">The traversed object.</returns>
- /// <remarks>Unlike the JSON reviver, this won't delete null members.</remarks>
return callback("", traverseInternal(item, "", callback));
};
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/store.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/store.js b/datajs/src/lib/store.js
index f943d3a..7e9263a 100644
--- a/datajs/src/lib/store.js
+++ b/datajs/src/lib/store.js
@@ -29,11 +29,13 @@ var mechanisms = {
exports.defaultStoreMechanism = "best";
+/** Creates a new store object.
+ * @param {String} name - Store name.
+ * @param {String} [mechanism] -
+ * @returns {Object} Store object.
+*/
exports.createStore = function (name, mechanism) {
- /// <summary>Creates a new store object.</summary>
- /// <param name="name" type="String">Store name.</param>
- /// <param name="mechanism" type="String" optional="true">A specific mechanism to use (defaults to best, can be "best", "dom", "indexeddb", "webdb").</param>
- /// <returns type="Object">Store object.</returns>
+
if (!mechanism) {
mechanism = exports.defaultStoreMechanism;
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/store/dom.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/store/dom.js b/datajs/src/lib/store/dom.js
index 13b7e1e..e9b09f3 100644
--- a/datajs/src/lib/store/dom.js
+++ b/datajs/src/lib/store/dom.js
@@ -25,13 +25,14 @@ var delay = utils.delay;
var localStorage = null;
+/** Converts a Date object into an object representation friendly to JSON serialization.
+ * @returns {Object} Object that represents the Date.
+
+ * This method is used to override the Date.toJSON method and is called only by
+ * JSON.stringify. It should never be called directly.
+ */
var domStoreDateToJSON = function () {
- /// <summary>Converts a Date object into an object representation friendly to JSON serialization.</summary>
- /// <returns type="Object">Object that represents the Date.</returns>
- /// <remarks>
- /// This method is used to override the Date.toJSON method and is called only by
- /// JSON.stringify. It should never be called directly.
- /// </remarks>
+
var newValue = { v: this.valueOf(), t: "[object Date]" };
// Date objects might have extra properties on them so we save them.
@@ -41,14 +42,16 @@ var domStoreDateToJSON = function () {
return newValue;
};
+/** JSON reviver function for converting an object representing a Date in a JSON stream to a Date object
+ * @param Object - Object to convert.
+ * @returns {Date} Date object.
+ * This method is used during JSON parsing and invoked only by the reviver function.
+ * It should never be called directly.
+ */
var domStoreJSONToDate = function (_, value) {
- /// <summary>JSON reviver function for converting an object representing a Date in a JSON stream to a Date object</summary>
- /// <param value="Object">Object to convert.</param>
- /// <returns type="Date">Date object.</returns>
- /// <remarks>
- /// This method is used during JSON parsing and invoked only by the reviver function.
- /// It should never be called directly.
- /// </remarks>
+
+
+
if (value && value.t === "[object Date]") {
var newValue = new Date(value.v);
@@ -62,34 +65,38 @@ var domStoreJSONToDate = function (_, value) {
return value;
};
+/** Qualifies the key with the name of the store.
+ * @param {Object} store - Store object whose name will be used for qualifying the key.
+ * @param {String} key - Key string.
+ * @returns {String} Fully qualified key string.
+ */
var qualifyDomStoreKey = function (store, key) {
- /// <summary>Qualifies the key with the name of the store.</summary>
- /// <param name="store" type="Object">Store object whose name will be used for qualifying the key.</param>
- /// <param name="key" type="String">Key string.</param>
- /// <returns type="String">Fully qualified key string.</returns>
return store.name + "#!#" + key;
};
+/** Gets the key part of a fully qualified key string.
+ * @param {Object} store - Store object whose name will be used for qualifying the key.
+ * @param {String} key - Fully qualified key string.
+ * @returns {String} Key part string
+ */
var unqualifyDomStoreKey = function (store, key) {
- /// <summary>Gets the key part of a fully qualified key string.</summary>
- /// <param name="store" type="Object">Store object whose name will be used for qualifying the key.</param>
- /// <param name="key" type="String">Fully qualified key string.</param>
- /// <returns type="String">Key part string</returns>
return key.replace(store.name + "#!#", "");
};
+/** Constructor for store objects that use DOM storage as the underlying mechanism.
+ * @param {String} name - Store name.
+ */
var DomStore = function (name) {
- /// <summary>Constructor for store objects that use DOM storage as the underlying mechanism.</summary>
- /// <param name="name" type="String">Store name.</param>
this.name = name;
};
+/** Creates a store object that uses DOM Storage as its underlying mechanism.
+ * @param {String} name - Store name.
+ * @returns {Object} Store object.
+ */
DomStore.create = function (name) {
- /// <summary>Creates a store object that uses DOM Storage as its underlying mechanism.</summary>
- /// <param name="name" type="String">Store name.</param>
- /// <returns type="Object">Store object.</returns>
if (DomStore.isSupported()) {
localStorage = localStorage || window.localStorage;
@@ -99,21 +106,22 @@ DomStore.create = function (name) {
throw { message: "Web Storage not supported by the browser" };
};
+/** Checks whether the underlying mechanism for this kind of store objects is supported by the browser.
+ * @returns {Boolean} - True if the mechanism is supported by the browser; otherwise false.
+*/
DomStore.isSupported = function () {
- /// <summary>Checks whether the underlying mechanism for this kind of store objects is supported by the browser.</summary>
- /// <returns type="Boolean">True if the mechanism is supported by the browser; otherwise false.</summary>
return !!window.localStorage;
};
+/** Adds a new value identified by a key to the store.
+ * @param {String} key - Key string.
+ * @param value - Value that is going to be added to the store.
+ * @param {Funcktion} success - Callback for a successful add operation.</param>
+ * @param {Funcktion} [error] - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+ * This method errors out if the store already contains the specified key.
+ */
DomStore.prototype.add = function (key, value, success, error) {
- /// <summary>Adds a new value identified by a key to the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="value">Value that is going to be added to the store.</param>
- /// <param name="success" type="Function" optional="no">Callback for a successful add operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
- /// <remarks>
- /// This method errors out if the store already contains the specified key.
- /// </remarks>
+
error = error || this.defaultError;
var store = this;
@@ -126,15 +134,16 @@ DomStore.prototype.add = function (key, value, success, error) {
}, error);
};
+/** Adds or updates a value identified by a key to the store.
+ * @param {String} key - Key string.
+ * @param value - Value that is going to be added or updated to the store.
+ * @param {Function} success - Callback for a successful add or update operation.</param>
+ * @param {Function} [error] - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+
+ * This method will overwrite the key's current value if it already exists in the store; otherwise it simply adds the new key and value.
+ */
DomStore.prototype.addOrUpdate = function (key, value, success, error) {
- /// <summary>Adds or updates a value identified by a key to the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="value">Value that is going to be added or updated to the store.</param>
- /// <param name="success" type="Function" optional="no">Callback for a successful add or update operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
- /// <remarks>
- /// This method will overwrite the key's current value if it already exists in the store; otherwise it simply adds the new key and value.
- /// </remarks>
+
error = error || this.defaultError;
@@ -167,13 +176,12 @@ DomStore.prototype.addOrUpdate = function (key, value, success, error) {
}
};
+/** Removes all the data associated with this store object.
+ * @param {Function} success - Callback for a successful clear operation.</param>
+ * @param {Function} [error] - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+ * In case of an error, this method will not restore any keys that might have been deleted at that point.
+ */
DomStore.prototype.clear = function (success, error) {
- /// <summary>Removes all the data associated with this store object.</summary>
- /// <param name="success" type="Function" optional="no">Callback for a successful clear operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
- /// <remarks>
- /// In case of an error, this method will not restore any keys that might have been deleted at that point.
- /// </remarks>
error = error || this.defaultError;
try {
@@ -195,15 +203,17 @@ DomStore.prototype.clear = function (success, error) {
}
};
+/** This function does nothing in DomStore as it does not have a connection model
+*/
DomStore.prototype.close = function () {
- /// <summary>This function does nothing in DomStore as it does not have a connection model</summary>
};
+/** Checks whether a key exists in the store.
+ * @param {String} key - Key string.
+ * @param {Function} success - Callback indicating whether the store contains the key or not.</param>
+ * @param {Function} [error] - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+*/
DomStore.prototype.contains = function (key, success, error) {
- /// <summary>Checks whether a key exists in the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="success" type="Function" optional="no">Callback indicating whether the store contains the key or not.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
error = error || this.defaultError;
try {
var fullKey = qualifyDomStoreKey(this, key);
@@ -216,10 +226,11 @@ DomStore.prototype.contains = function (key, success, error) {
DomStore.prototype.defaultError = throwErrorCallback;
+/** Gets all the keys that exist in the store.
+ * @param {Function} success - Callback for a successful get operation.</param>
+ * @param {Function} [error] - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+ */
DomStore.prototype.getAllKeys = function (success, error) {
- /// <summary>Gets all the keys that exist in the store.</summary>
- /// <param name="success" type="Function" optional="no">Callback for a successful get operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
error = error || this.defaultError;
@@ -241,14 +252,16 @@ DomStore.prototype.getAllKeys = function (success, error) {
}
};
-/// <summary>Identifies the underlying mechanism used by the store.</summary>
+/** Identifies the underlying mechanism used by the store.*/
DomStore.prototype.mechanism = "dom";
+/** Reads the value associated to a key in the store.
+ * @param {String} key - Key string.
+ * @param {Function} success - Callback for a successful reads operation.
+ * @param {Function} [error] - Callback for handling errors. If not specified then store.defaultError is invoked.
+ */
DomStore.prototype.read = function (key, success, error) {
- /// <summary>Reads the value associated to a key in the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="success" type="Function" optional="no">Callback for a successful reads operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+
error = error || this.defaultError;
if (key instanceof Array) {
@@ -271,11 +284,12 @@ DomStore.prototype.read = function (key, success, error) {
}
};
+/** Removes a key and its value from the store.
+ * @param {String} key - Key string.
+ * @param {Funtion} success - Callback for a successful remove operation.</param>
+ * @param {Funtion} [error] - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+ */
DomStore.prototype.remove = function (key, success, error) {
- /// <summary>Removes a key and its value from the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="success" type="Function" optional="no">Callback for a successful remove operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
error = error || this.defaultError;
if (key instanceof Array) {
@@ -291,15 +305,15 @@ DomStore.prototype.remove = function (key, success, error) {
}
};
+/** Updates the value associated to a key in the store.
+ * @param {String} key - Key string.
+ * @param value - New value.
+ * @param {Function} success - Callback for a successful update operation.
+ * @param {Function} [error] - Callback for handling errors. If not specified then store.defaultError is invoked
+ * This method errors out if the specified key is not found in the store.
+ */
DomStore.prototype.update = function (key, value, success, error) {
- /// <summary>Updates the value associated to a key in the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="value">New value.</param>
- /// <param name="success" type="Function" optional="no">Callback for a successful update operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
- /// <remarks>
- /// This method errors out if the specified key is not found in the store.
- /// </remarks>
+
error = error || this.defaultError;
var store = this;
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/store/indexeddb.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/store/indexeddb.js b/datajs/src/lib/store/indexeddb.js
index f71b62e..1570dd6 100644
--- a/datajs/src/lib/store/indexeddb.js
+++ b/datajs/src/lib/store/indexeddb.js
@@ -31,11 +31,12 @@ var IDBTransaction = window.IDBTransaction || window.webkitIDBTransaction || {};
var IDBT_READ_ONLY = IDBTransaction.READ_ONLY || "readonly";
var IDBT_READ_WRITE = IDBTransaction.READ_WRITE || "readwrite";
+/** Returns either a specific error handler or the default error handler
+ * @param {Function} error - The specific error handler
+ * @param {Function} defaultError - The default error handler
+ * @returns {Function} The error callback
+ */
var getError = function (error, defaultError) {
- /// <summary>Returns either a specific error handler or the default error handler</summary>
- /// <param name="error" type="Function">The specific error handler</param>
- /// <param name="defaultError" type="Function">The default error handler</param>
- /// <returns type="Function">The error callback</returns>
return function (e) {
var errorFunc = error || defaultError;
@@ -64,11 +65,12 @@ var getError = function (error, defaultError) {
};
};
+/** Opens the store object's indexed db database.
+ * @param {IndexedDBStore} store - The store object
+ * @param {Function} success - The success callback
+ * @param {Function} error - The error callback
+ */
var openStoreDb = function (store, success, error) {
- /// <summary>Opens the store object's indexed db database.</summary>
- /// <param name="store" type="IndexedDBStore">The store object</param>
- /// <param name="success" type="Function">The success callback</param>
- /// <param name="error" type="Function">The error callback</param>
var storeName = store.name;
var dbName = "_datajs_" + storeName;
@@ -117,12 +119,13 @@ var openStoreDb = function (store, success, error) {
};
};
+/** Opens a new transaction to the store
+ * @param {IndexedDBStore} store - The store object
+ * @param {Short} mode - The read/write mode of the transaction (constants from IDBTransaction)
+ * @param {Function} success - The success callback
+ * @param {Function} error - The error callback
+ */
var openTransaction = function (store, mode, success, error) {
- /// <summary>Opens a new transaction to the store</summary>
- /// <param name="store" type="IndexedDBStore">The store object</param>
- /// <param name="mode" type="Short">The read/write mode of the transaction (constants from IDBTransaction)</param>
- /// <param name="success" type="Function">The success callback</param>
- /// <param name="error" type="Function">The error callback</param>
var storeName = store.name;
var storeDb = store.db;
@@ -139,17 +142,19 @@ var openTransaction = function (store, mode, success, error) {
}, errorCallback);
};
+/** Creates a new IndexedDBStore.
+ * @param {String} name - The name of the store.
+ * @returns {Object} The new IndexedDBStore.
+ */
var IndexedDBStore = function (name) {
- /// <summary>Creates a new IndexedDBStore.</summary>
- /// <param name="name" type="String">The name of the store.</param>
- /// <returns type="Object">The new IndexedDBStore.</returns>
this.name = name;
};
+/** Creates a new IndexedDBStore.
+ * @param {String} name - The name of the store.
+ * @returns {Object} The new IndexedDBStore.
+ */
IndexedDBStore.create = function (name) {
- /// <summary>Creates a new IndexedDBStore.</summary>
- /// <param name="name" type="String">The name of the store.</param>
- /// <returns type="Object">The new IndexedDBStore.</returns>
if (IndexedDBStore.isSupported()) {
return new IndexedDBStore(name);
}
@@ -157,18 +162,20 @@ IndexedDBStore.create = function (name) {
throw { message: "IndexedDB is not supported on this browser" };
};
+/** Returns whether IndexedDB is supported.
+ * @returns {Boolean} True if IndexedDB is supported, false otherwise.
+ */
IndexedDBStore.isSupported = function () {
- /// <summary>Returns whether IndexedDB is supported.</summary>
- /// <returns type="Boolean">True if IndexedDB is supported, false otherwise.</returns>
return !!indexedDB;
};
+/** Adds a key/value pair to the store
+ * @param {String} key - The key
+ * @param {Object} value - The value
+ * @param {Function} success - The success callback
+ * @param {Function} error - The error callback
+*/
IndexedDBStore.prototype.add = function (key, value, success, error) {
- /// <summary>Adds a key/value pair to the store</summary>
- /// <param name="key" type="String">The key</param>
- /// <param name="value" type="Object">The value</param>
- /// <param name="success" type="Function">The success callback</param>
- /// <param name="error" type="Function">The error callback</param>
var name = this.name;
var defaultError = this.defaultError;
var keys = [];
@@ -198,12 +205,13 @@ IndexedDBStore.prototype.add = function (key, value, success, error) {
}, error);
};
+/** Adds or updates a key/value pair in the store
+ * @param {String} key - The key
+ * @param {Object} value - The value
+ * @param {Function} success - The success callback
+ * @param {Function} error - The error callback
+ */
IndexedDBStore.prototype.addOrUpdate = function (key, value, success, error) {
- /// <summary>Adds or updates a key/value pair in the store</summary>
- /// <param name="key" type="String">The key</param>
- /// <param name="value" type="Object">The value</param>
- /// <param name="success" type="Function">The success callback</param>
- /// <param name="error" type="Function">The error callback</param>
var name = this.name;
var defaultError = this.defaultError;
var keys = [];
@@ -234,10 +242,11 @@ IndexedDBStore.prototype.addOrUpdate = function (key, value, success, error) {
}, error);
};
+/** Clears the store
+ * @param {Function} success - The success callback
+ * @param {Function} error - The error callback
+ */
IndexedDBStore.prototype.clear = function (success, error) {
- /// <summary>Clears the store</summary>
- /// <param name="success" type="Function">The success callback</param>
- /// <param name="error" type="Function">The error callback</param>
var name = this.name;
var defaultError = this.defaultError;
openTransaction(this, IDBT_READ_WRITE, function (transaction) {
@@ -251,18 +260,20 @@ IndexedDBStore.prototype.clear = function (success, error) {
};
IndexedDBStore.prototype.close = function () {
- /// <summary>Closes the connection to the database</summary>
+ /** Closes the connection to the database
+ */
if (this.db) {
this.db.close();
this.db = null;
}
};
+/** Returns whether the store contains a key
+ * @param {String} key - The key
+ * @param {Function} success - The success callback
+ * @param {Function} error - The error callback
+ */
IndexedDBStore.prototype.contains = function (key, success, error) {
- /// <summary>Returns whether the store contains a key</summary>
- /// <param name="key" type="String">The key</param>
- /// <param name="success" type="Function">The success callback</param>
- /// <param name="error" type="Function">The error callback</param>
var name = this.name;
var defaultError = this.defaultError;
openTransaction(this, IDBT_READ_ONLY, function (transaction) {
@@ -278,10 +289,11 @@ IndexedDBStore.prototype.contains = function (key, success, error) {
IndexedDBStore.prototype.defaultError = throwErrorCallback;
+/** Gets all the keys from the store
+ * @param {Function} success - The success callback
+ * @param {Function} error - The error callback
+ */
IndexedDBStore.prototype.getAllKeys = function (success, error) {
- /// <summary>Gets all the keys from the store</summary>
- /// <param name="success" type="Function">The success callback</param>
- /// <param name="error" type="Function">The error callback</param>
var name = this.name;
var defaultError = this.defaultError;
openTransaction(this, IDBT_READ_WRITE, function (transaction) {
@@ -305,15 +317,17 @@ IndexedDBStore.prototype.getAllKeys = function (success, error) {
}, error);
};
-/// <summary>Identifies the underlying mechanism used by the store.</summary>
+/** Identifies the underlying mechanism used by the store.
+*/
IndexedDBStore.prototype.mechanism = "indexeddb";
+/** Reads the value for the specified key
+ * @param {String} key - The key
+ * @param {Function} success - The success callback
+ * @param {Function} error - The error callback
+ * If the key does not exist, the success handler will be called with value = undefined
+ */
IndexedDBStore.prototype.read = function (key, success, error) {
- /// <summary>Reads the value for the specified key</summary>
- /// <param name="key" type="String">The key</param>
- /// <param name="success" type="Function">The success callback</param>
- /// <param name="error" type="Function">The error callback</param>
- /// <remarks>If the key does not exist, the success handler will be called with value = undefined</remarks>
var name = this.name;
var defaultError = this.defaultError;
var keys = (key instanceof Array) ? key : [key];
@@ -342,11 +356,13 @@ IndexedDBStore.prototype.read = function (key, success, error) {
}, error);
};
+/** Removes the specified key from the store
+ * @param {String} key - The key
+ * @param {Function} success - The success callback
+ * @param {Function} error - The error callback
+ */
IndexedDBStore.prototype.remove = function (key, success, error) {
- /// <summary>Removes the specified key from the store</summary>
- /// <param name="key" type="String">The key</param>
- /// <param name="success" type="Function">The success callback</param>
- /// <param name="error" type="Function">The error callback</param>
+
var name = this.name;
var defaultError = this.defaultError;
var keys = (key instanceof Array) ? key : [key];
@@ -365,12 +381,13 @@ IndexedDBStore.prototype.remove = function (key, success, error) {
}, error);
};
+/** Updates a key/value pair in the store
+ * @param {String} key - The key
+ * @param {Object} value - The value
+ * @param {Function} success - The success callback
+ * @param {Function} error - The error callback
+ */
IndexedDBStore.prototype.update = function (key, value, success, error) {
- /// <summary>Updates a key/value pair in the store</summary>
- /// <param name="key" type="String">The key</param>
- /// <param name="value" type="Object">The value</param>
- /// <param name="success" type="Function">The success callback</param>
- /// <param name="error" type="Function">The error callback</param>
var name = this.name;
var defaultError = this.defaultError;
var keys = [];
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/store/memory.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/store/memory.js b/datajs/src/lib/store/memory.js
index 464cdec..e91902f 100644
--- a/datajs/src/lib/store/memory.js
+++ b/datajs/src/lib/store/memory.js
@@ -24,9 +24,10 @@ var utils = require('./../datajs.js').utils;
var throwErrorCallback = utils.throwErrorCallback;
var delay = utils.delay;
+/** Constructor for store objects that use a sorted array as the underlying mechanism.
+ * @param {String} name - Store name.
+ */
var MemoryStore = function (name) {
- /// <summary>Constructor for store objects that use a sorted array as the underlying mechanism.</summary>
- /// <param name="name" type="String">Store name.</param>
var holes = [];
var items = [];
@@ -38,11 +39,12 @@ var MemoryStore = function (name) {
return error || this.defaultError;
};
+ /** Validates that the specified key is not undefined, not null, and not an array
+ * @param key - Key value.
+ * @param {Function} error - Error callback.
+ * @returns {Boolean} True if the key is valid. False if the key is invalid and the error callback has been queued for execution.
+ */
var validateKeyInput = function (key, error) {
- /// <summary>Validates that the specified key is not undefined, not null, and not an array</summary>
- /// <param name="key">Key value.</param>
- /// <param name="error" type="Function">Error callback.</param>
- /// <returns type="Boolean">True if the key is valid. False if the key is invalid and the error callback has been queued for execution.</returns>
var messageString;
@@ -61,16 +63,15 @@ var MemoryStore = function (name) {
return true;
};
+ /** Adds a new value identified by a key to the store.
+ * @param {String} key - Key string.
+ * @param value - Value that is going to be added to the store.
+ * @param {Function} success - Callback for a successful add operation.</param>
+ * @param {Function} error - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+
+ * This method errors out if the store already contains the specified key.
+ */
this.add = function (key, value, success, error) {
- /// <summary>Adds a new value identified by a key to the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="value">Value that is going to be added to the store.</param>
- /// <param name="success" type="Function" optional="no">Callback for a successful add operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
- /// <remarks>
- /// This method errors out if the store already contains the specified key.
- /// </remarks>
-
error = getErrorCallback(error);
if (validateKeyInput(key, error)) {
@@ -83,14 +84,16 @@ var MemoryStore = function (name) {
};
this.addOrUpdate = function (key, value, success, error) {
- /// <summary>Adds or updates a value identified by a key to the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="value">Value that is going to be added or updated to the store.</param>
- /// <param name="success" type="Function" optional="no">Callback for a successful add or update operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
- /// <remarks>
- /// This method will overwrite the key's current value if it already exists in the store; otherwise it simply adds the new key and value.
- /// </remarks>
+ /** Adds or updates a value identified by a key to the store.
+ * @param {String} key - Key string.
+ * @param value - Value that is going to be added or updated to the store.
+ *@param {Function} success - Callback for a successful add or update operation.</param>
+ *@param {Function} [error] - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+
+ This method will overwrite the key's current value if it already exists in the store; otherwise it simply adds the new key and value.
+
+ */
+
error = getErrorCallback(error);
@@ -110,8 +113,9 @@ var MemoryStore = function (name) {
};
this.clear = function (success) {
- /// <summary>Removes all the data associated with this store object.</summary>
- /// <param name="success" type="Function" optional="no">Callback for a successful clear operation.</param>
+ /** Removes all the data associated with this store object.
+ * @param {Function} success>Callback for a successful clear operation.
+ */
items = [];
keys = {};
@@ -120,18 +124,20 @@ var MemoryStore = function (name) {
delay(success);
};
+ /** Checks whether a key exists in the store.
+ * @param {String} key - Key string.
+ * @param {Funktion} success - Callback indicating whether the store contains the key or not.</param>
+ */
this.contains = function (key, success) {
- /// <summary>Checks whether a key exists in the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="success" type="Function" optional="no">Callback indicating whether the store contains the key or not.</param>
var contained = keys.hasOwnProperty(key);
delay(success, contained);
};
+ /** Gets all the keys that exist in the store.
+ * @param {Function} success - Callback for a successful get operation.</param>
+ */
this.getAllKeys = function (success) {
- /// <summary>Gets all the keys that exist in the store.</summary>
- /// <param name="success" type="Function" optional="no">Callback for a successful get operation.</param>
var results = [];
for (var name in keys) {
@@ -140,11 +146,12 @@ var MemoryStore = function (name) {
delay(success, results);
};
+ /** Reads the value associated to a key in the store.
+ * @param {String} key - Key string.
+ * @param {Function} Function - Callback for a successful reads operation.</param>
+ * @param {Function{}Function - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+ */
this.read = function (key, success, error) {
- /// <summary>Reads the value associated to a key in the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="success" type="Function" optional="no">Callback for a successful reads operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
error = getErrorCallback(error);
if (validateKeyInput(key, error)) {
@@ -153,11 +160,12 @@ var MemoryStore = function (name) {
}
};
+/** Removes a key and its value from the store.
+ * @param {String} key - Key string.
+ * @param {Function} success - Callback for a successful remove operation.</param>
+ * @param {Function} [error] - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+*/
this.remove = function (key, success, error) {
- /// <summary>Removes a key and its value from the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="success" type="Function" optional="no">Callback for a successful remove operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
error = getErrorCallback(error);
if (validateKeyInput(key, error)) {
@@ -181,15 +189,16 @@ var MemoryStore = function (name) {
}
};
+ /** Updates the value associated to a key in the store.
+ * @param {String} key - Key string.
+ * @param value - New value.
+ * @param {Function} success - Callback for a successful update operation.</param>
+ * @param {Function} [error] - Callback for handling errors. If not specified then store.defaultError is invoked.</param>
+
+ * This method errors out if the specified key is not found in the store.
+ */
this.update = function (key, value, success, error) {
- /// <summary>Updates the value associated to a key in the store.</summary>
- /// <param name="key" type="String">Key string.</param>
- /// <param name="value">New value.</param>
- /// <param name="success" type="Function" optional="no">Callback for a successful update operation.</param>
- /// <param name="error" type="Function" optional="yes">Callback for handling errors. If not specified then store.defaultError is invoked.</param>
- /// <remarks>
- /// This method errors out if the specified key is not found in the store.
- /// </remarks>
+
error = getErrorCallback(error);
if (validateKeyInput(key, error)) {
@@ -202,26 +211,30 @@ var MemoryStore = function (name) {
};
};
+/** Creates a store object that uses memory storage as its underlying mechanism.
+ * @param {String} name - Store name.
+ * @returns {Object} Store object.
+ */
MemoryStore.create = function (name) {
- /// <summary>Creates a store object that uses memory storage as its underlying mechanism.</summary>
- /// <param name="name" type="String">Store name.</param>
- /// <returns type="Object">Store object.</returns>
return new MemoryStore(name);
};
+/** Checks whether the underlying mechanism for this kind of store objects is supported by the browser.
+ * @returns {Boolean} True if the mechanism is supported by the browser; otherwise false.
+ */
MemoryStore.isSupported = function () {
- /// <summary>Checks whether the underlying mechanism for this kind of store objects is supported by the browser.</summary>
- /// <returns type="Boolean">True if the mechanism is supported by the browser; otherwise false.</returns>
return true;
};
+/** This function does nothing in MemoryStore as it does not have a connection model.
+*/
MemoryStore.prototype.close = function () {
- /// <summary>This function does nothing in MemoryStore as it does not have a connection model.</summary>
};
MemoryStore.prototype.defaultError = throwErrorCallback;
-/// <summary>Identifies the underlying mechanism used by the store.</summary>
+/** Identifies the underlying mechanism used by the store.
+*/
MemoryStore.prototype.mechanism = "memory";
module.exports = MemoryStore;
[2/3] [OLINGO-408] first conversion of the doc comments
Posted by ko...@apache.org.
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/datajs/xml.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/datajs/xml.js b/datajs/src/lib/datajs/xml.js
index ca5c899..16e505f 100644
--- a/datajs/src/lib/datajs/xml.js
+++ b/datajs/src/lib/datajs/xml.js
@@ -35,28 +35,32 @@ var xmlNS = w3org + "XML/1998/namespace"; // http://www.w3.org/XML/1998/na
var mozillaParserErroNS = http + "www.mozilla.org/newlayout/xml/parsererror.xml";
+/** Checks whether the specified string has leading or trailing spaces.
+ * @param {String} text - String to check.
+ * @returns {Boolean} true if text has any leading or trailing whitespace; false otherwise.
+ */
var hasLeadingOrTrailingWhitespace = function (text) {
- /// <summary>Checks whether the specified string has leading or trailing spaces.</summary>
- /// <param name="text" type="String">String to check.</param>
- /// <returns type="Boolean">true if text has any leading or trailing whitespace; false otherwise.</returns>
-
var re = /(^\s)|(\s$)/;
return re.test(text);
};
+/** Determines whether the specified text is empty or whitespace.
+ * @param {String} text - Value to inspect.
+ * @returns {Boolean} true if the text value is empty or all whitespace; false otherwise.
+ */
var isWhitespace = function (text) {
- /// <summary>Determines whether the specified text is empty or whitespace.</summary>
- /// <param name="text" type="String">Value to inspect.</param>
- /// <returns type="Boolean">true if the text value is empty or all whitespace; false otherwise.</returns>
+
var ws = /^\s*$/;
return text === null || ws.test(text);
};
+/** Determines whether the specified element has xml:space='preserve' applied.
+ * @param domElement - Element to inspect.
+ * @returns {Boolean} Whether xml:space='preserve' is in effect.
+ */
var isWhitespacePreserveContext = function (domElement) {
- /// <summary>Determines whether the specified element has xml:space='preserve' applied.</summary>
- /// <param name="domElement">Element to inspect.</param>
- /// <returns type="Boolean">Whether xml:space='preserve' is in effect.</returns>
+
while (domElement !== null && domElement.nodeType === 1) {
var val = xmlAttributeValue(domElement, "space", xmlNS);
@@ -72,35 +76,34 @@ var isWhitespacePreserveContext = function (domElement) {
return false;
};
+/** Determines whether the attribute is a XML namespace declaration.
+ * @param domAttribute - Element to inspect.
+ * @return {Boolean} True if the attribute is a namespace declaration (its name is 'xmlns' or starts with 'xmlns:'; false otherwise.
+ */
var isXmlNSDeclaration = function (domAttribute) {
- /// <summary>Determines whether the attribute is a XML namespace declaration.</summary>
- /// <param name="domAttribute">Element to inspect.</param>
- /// <returns type="Boolean">
- /// True if the attribute is a namespace declaration (its name is 'xmlns' or starts with 'xmlns:'; false otherwise.
- /// </returns>
-
var nodeName = domAttribute.nodeName;
return nodeName == "xmlns" || nodeName.indexOf("xmlns:") === 0;
};
+/** Safely set as property in an object by invoking obj.setProperty.
+ * @param obj - Object that exposes a setProperty method.
+ * @param {String} name - Property name
+ * @param value - Property value.
+ */
var safeSetProperty = function (obj, name, value) {
- /// <summary>Safely set as property in an object by invoking obj.setProperty.</summary>
- /// <param name="obj">Object that exposes a setProperty method.</param>
- /// <param name="name" type="String" mayBeNull="false">Property name.</param>
- /// <param name="value">Property value.</param>
+
try {
obj.setProperty(name, value);
} catch (_) { }
};
+/** Creates an configures new MSXML 3.0 ActiveX object.
+ * @returns {Object} New MSXML 3.0 ActiveX object.
+ * This function throws any exception that occurs during the creation
+ * of the MSXML 3.0 ActiveX object.
+ */
var msXmlDom3 = function () {
- /// <summary>Creates an configures new MSXML 3.0 ActiveX object.</summary>
- /// <remakrs>
- /// This function throws any exception that occurs during the creation
- /// of the MSXML 3.0 ActiveX object.
- /// <returns type="Object">New MSXML 3.0 ActiveX object.</returns>
-
var msxml3 = activeXObject("Msxml2.DOMDocument.3.0");
if (msxml3) {
safeSetProperty(msxml3, "ProhibitDTD", true);
@@ -111,15 +114,14 @@ var msXmlDom3 = function () {
return msxml3;
};
+/** Creates an configures new MSXML 6.0 or MSXML 3.0 ActiveX object.
+ * @returns {Object} New MSXML 3.0 ActiveX object.
+ * This function will try to create a new MSXML 6.0 ActiveX object. If it fails then
+ * it will fallback to create a new MSXML 3.0 ActiveX object. Any exception that
+ * happens during the creation of the MSXML 6.0 will be handled by the function while
+ * the ones that happend during the creation of the MSXML 3.0 will be thrown.
+ */
var msXmlDom = function () {
- /// <summary>Creates an configures new MSXML 6.0 or MSXML 3.0 ActiveX object.</summary>
- /// <remakrs>
- /// This function will try to create a new MSXML 6.0 ActiveX object. If it fails then
- /// it will fallback to create a new MSXML 3.0 ActiveX object. Any exception that
- /// happens during the creation of the MSXML 6.0 will be handled by the function while
- /// the ones that happend during the creation of the MSXML 3.0 will be thrown.
- /// <returns type="Object">New MSXML 3.0 ActiveX object.</returns>
-
try {
var msxml = activeXObject("Msxml2.DOMDocument.6.0");
if (msxml) {
@@ -131,14 +133,13 @@ var msXmlDom = function () {
}
};
+/** Parses an XML string using the MSXML DOM.
+ * @returns {Object} New MSXML DOMDocument node representing the parsed XML string.
+ * This function throws any exception that occurs during the creation
+ * of the MSXML ActiveX object. It also will throw an exception
+ * in case of a parsing error.
+ */
var msXmlParse = function (text) {
- /// <summary>Parses an XML string using the MSXML DOM.</summary>
- /// <remakrs>
- /// This function throws any exception that occurs during the creation
- /// of the MSXML ActiveX object. It also will throw an exception
- /// in case of a parsing error.
- /// <returns type="Object">New MSXML DOMDocument node representing the parsed XML string.</returns>
-
var dom = msXmlDom();
if (!dom) {
return null;
@@ -152,16 +153,12 @@ var msXmlParse = function (text) {
return dom;
};
+/** Throws a new exception containing XML parsing error information.
+ * @param exceptionOrReason - String indicating the reason of the parsing failure or Object detailing the parsing error.
+ * @param {String} srcText - String indicating the part of the XML string that caused the parsing error.
+ * @param {String} errorXmlText - XML string for wich the parsing failed.
+ */
var xmlThrowParserError = function (exceptionOrReason, srcText, errorXmlText) {
- /// <summary>Throws a new exception containing XML parsing error information.</summary>
- /// <param name="exceptionOrReason">
- /// String indicatin the reason of the parsing failure or
- /// Object detailing the parsing error.
- /// </param>
- /// <param name="srcText" type="String">
- /// String indicating the part of the XML string that caused the parsing error.
- /// </param>
- /// <param name="errorXmlText" type="String">XML string for wich the parsing failed.</param>
if (typeof exceptionOrReason === "string") {
exceptionOrReason = { message: exceptionOrReason };
@@ -169,12 +166,12 @@ var xmlThrowParserError = function (exceptionOrReason, srcText, errorXmlText) {
throw extend(exceptionOrReason, { srcText: srcText || "", errorXmlText: errorXmlText || "" });
};
+/** Returns an XML DOM document from the specified text.
+ * @param {String} text - Document text.
+ * @returns XML DOM document.
+ * This function will throw an exception in case of a parse error
+ */
var xmlParse = function (text) {
- /// <summary>Returns an XML DOM document from the specified text.</summary>
- /// <param name="text" type="String">Document text.</param>
- /// <returns>XML DOM document.</returns>
- /// <remarks>This function will throw an exception in case of a parse error.</remarks>
-
var domParser = window.DOMParser && new window.DOMParser();
var dom;
@@ -224,19 +221,20 @@ var xmlParse = function (text) {
return dom;
};
+/** Builds a XML qualified name string in the form of "prefix:name".
+ * @param {String} prefix - Prefix string (may be null)
+ * @param {String} name - Name string to qualify with the prefix.
+ * @returns {String} Qualified name.
+ */
var xmlQualifiedName = function (prefix, name) {
- /// <summary>Builds a XML qualified name string in the form of "prefix:name".</summary>
- /// <param name="prefix" type="String" maybeNull="true">Prefix string.</param>
- /// <param name="name" type="String">Name string to qualify with the prefix.</param>
- /// <returns type="String">Qualified name.</returns>
-
return prefix ? prefix + ":" + name : name;
};
+/** Appends a text node into the specified DOM element node.
+ * @param domNode - DOM node for the element.
+ * @param {String} text - Text to append as a child of element.
+*/
var xmlAppendText = function (domNode, textNode) {
- /// <summary>Appends a text node into the specified DOM element node.</summary>
- /// <param name="domNode">DOM node for the element.</param>
- /// <param name="text" type="String" mayBeNull="false">Text to append as a child of element.</param>
if (hasLeadingOrTrailingWhitespace(textNode.data)) {
var attr = xmlAttributeNode(domNode, xmlNS, "space");
if (!attr) {
@@ -249,11 +247,11 @@ var xmlAppendText = function (domNode, textNode) {
return domNode;
};
+/** Iterates through the XML element's attributes and invokes the callback function for each one.
+ * @param element - Wrapped element to iterate over.
+ * @param {Function} onAttributeCallback - Callback function to invoke with wrapped attribute nodes.
+*/
var xmlAttributes = function (element, onAttributeCallback) {
- /// <summary>Iterates through the XML element's attributes and invokes the callback function for each one.</summary>
- /// <param name="element">Wrapped element to iterate over.</param>
- /// <param name="onAttributeCallback" type="Function">Callback function to invoke with wrapped attribute nodes.</param>
-
var attributes = element.attributes;
var i, len;
for (i = 0, len = attributes.length; i < len; i++) {
@@ -261,23 +259,25 @@ var xmlAttributes = function (element, onAttributeCallback) {
}
};
+/** Returns the value of a DOM element's attribute.
+ * @param domNode - DOM node for the owning element.
+ * @param {String} localName - Local name of the attribute.
+ * @param {String} nsURI - Namespace URI of the attribute.
+ * @returns {String} - The attribute value, null if not found (may be null)
+ */
var xmlAttributeValue = function (domNode, localName, nsURI) {
- /// <summary>Returns the value of a DOM element's attribute.</summary>
- /// <param name="domNode">DOM node for the owning element.</param>
- /// <param name="localName" type="String">Local name of the attribute.</param>
- /// <param name="nsURI" type="String">Namespace URI of the attribute.</param>
- /// <returns type="String" maybeNull="true">The attribute value, null if not found.</returns>
var attribute = xmlAttributeNode(domNode, localName, nsURI);
return attribute ? xmlNodeValue(attribute) : null;
};
+/** Gets an attribute node from a DOM element.
+ * @param domNode - DOM node for the owning element.
+ * @param {String} localName - Local name of the attribute.
+ * @param {String} nsURI - Namespace URI of the attribute.
+ * @returns The attribute node, null if not found.
+ */
var xmlAttributeNode = function (domNode, localName, nsURI) {
- /// <summary>Gets an attribute node from a DOM element.</summary>
- /// <param name="domNode">DOM node for the owning element.</param>
- /// <param name="localName" type="String">Local name of the attribute.</param>
- /// <param name="nsURI" type="String">Namespace URI of the attribute.</param>
- /// <returns>The attribute node, null if not found.</returns>
var attributes = domNode.attributes;
if (attributes.getNamedItemNS) {
@@ -287,21 +287,23 @@ var xmlAttributeNode = function (domNode, localName, nsURI) {
return attributes.getQualifiedItem(localName, nsURI) || null;
};
+/** Gets the value of the xml:base attribute on the specified element.
+ * @param domNode - Element to get xml:base attribute value from.
+ * @param [baseURI] - Base URI used to normalize the value of the xml:base attribute ( may be null)
+ * @returns {String} Value of the xml:base attribute if found; the baseURI or null otherwise.
+ */
var xmlBaseURI = function (domNode, baseURI) {
- /// <summary>Gets the value of the xml:base attribute on the specified element.</summary>
- /// <param name="domNode">Element to get xml:base attribute value from.</param>
- /// <param name="baseURI" mayBeNull="true" optional="true">Base URI used to normalize the value of the xml:base attribute.</param>
- /// <returns type="String">Value of the xml:base attribute if found; the baseURI or null otherwise.</returns>
var base = xmlAttributeNode(domNode, "base", xmlNS);
return (base ? normalizeURI(base.value, baseURI) : baseURI) || null;
};
+/** Iterates through the XML element's child DOM elements and invokes the callback function for each one.
+ * @param element - DOM Node containing the DOM elements to iterate over.
+ * @param {Function} onElementCallback - Callback function to invoke for each child DOM element.
+*/
var xmlChildElements = function (domNode, onElementCallback) {
- /// <summary>Iterates through the XML element's child DOM elements and invokes the callback function for each one.</summary>
- /// <param name="element">DOM Node containing the DOM elements to iterate over.</param>
- /// <param name="onElementCallback" type="Function">Callback function to invoke for each child DOM element.</param>
xmlTraverse(domNode, /*recursive*/false, function (child) {
if (child.nodeType === 1) {
@@ -312,17 +314,15 @@ var xmlChildElements = function (domNode, onElementCallback) {
});
};
+/** Gets the descendant element under root that corresponds to the specified path and namespace URI.
+ * @param root - DOM element node from which to get the descendant element.
+ * @param {String} namespaceURI - The namespace URI of the element to match.
+ * @param {String} path - Path to the desired descendant element.
+ * @return The element specified by path and namespace URI.
+ * All the elements in the path are matched against namespaceURI.
+ * The function will stop searching on the first element that doesn't match the namespace and the path.
+ */
var xmlFindElementByPath = function (root, namespaceURI, path) {
- /// <summary>Gets the descendant element under root that corresponds to the specified path and namespace URI.</summary>
- /// <param name="root">DOM element node from which to get the descendant element.</param>
- /// <param name="namespaceURI" type="String">The namespace URI of the element to match.</param>
- /// <param name="path" type="String">Path to the desired descendant element.</param>
- /// <returns>The element specified by path and namespace URI.</returns>
- /// <remarks>
- /// All the elements in the path are matched against namespaceURI.
- /// The function will stop searching on the first element that doesn't match the namespace and the path.
- /// </remarks>
-
var parts = path.split("/");
var i, len;
for (i = 0, len = parts.length; i < len; i++) {
@@ -331,18 +331,18 @@ var xmlFindElementByPath = function (root, namespaceURI, path) {
return root || null;
};
+/** Gets the DOM element or DOM attribute node under root that corresponds to the specified path and namespace URI.
+ * @param root - DOM element node from which to get the descendant node.
+ * @param {String} namespaceURI - The namespace URI of the node to match.
+ * @param {String} path - Path to the desired descendant node.
+ * @return The node specified by path and namespace URI.</returns>
+
+* This function will traverse the path and match each node associated to a path segement against the namespace URI.
+* The traversal stops when the whole path has been exahusted or a node that doesn't belogong the specified namespace is encountered.
+* The last segment of the path may be decorated with a starting @ character to indicate that the desired node is a DOM attribute.
+*/
var xmlFindNodeByPath = function (root, namespaceURI, path) {
- /// <summary>Gets the DOM element or DOM attribute node under root that corresponds to the specified path and namespace URI.</summary>
- /// <param name="root">DOM element node from which to get the descendant node.</param>
- /// <param name="namespaceURI" type="String">The namespace URI of the node to match.</param>
- /// <param name="path" type="String">Path to the desired descendant node.</param>
- /// <returns>The node specified by path and namespace URI.</returns>
- /// <remarks>
- /// This function will traverse the path and match each node associated to a path segement against the namespace URI.
- /// The traversal stops when the whole path has been exahusted or a node that doesn't belogong the specified namespace is encountered.
- ///
- /// The last segment of the path may be decorated with a starting @ character to indicate that the desired node is a DOM attribute.
- /// </remarks>
+
var lastSegmentStart = path.lastIndexOf("/");
var nodePath = path.substring(lastSegmentStart + 1);
@@ -358,23 +358,24 @@ var xmlFindNodeByPath = function (root, namespaceURI, path) {
return null;
};
+/** Returns the first child DOM element under the specified DOM node that matches the specified namespace URI and local name.
+ * @param domNode - DOM node from which the child DOM element is going to be retrieved.
+ * @param {String} [namespaceURI] -
+ * @param {String} [localName] -
+ * @return The node's first child DOM element that matches the specified namespace URI and local name; null otherwise.</returns>
+ */
var xmlFirstChildElement = function (domNode, namespaceURI, localName) {
- /// <summary>Returns the first child DOM element under the specified DOM node that matches the specified namespace URI and local name.</summary>
- /// <param name="domNode">DOM node from which the child DOM element is going to be retrieved.</param>
- /// <param name="namespaceURI" type="String" optional="true">The namespace URI of the element to match.</param>
- /// <param name="localName" type="String" optional="true">Name of the element to match.</param>
- /// <returns>The node's first child DOM element that matches the specified namespace URI and local name; null otherwise.</returns>
return xmlFirstElementMaybeRecursive(domNode, namespaceURI, localName, /*recursive*/false);
};
+/** Returns the first descendant DOM element under the specified DOM node that matches the specified namespace URI and local name.
+ * @param domNode - DOM node from which the descendant DOM element is going to be retrieved.
+ * @param {String} [namespaceURI] -
+ * @param {String} [localName] -
+ * @return The node's first descendant DOM element that matches the specified namespace URI and local name; null otherwise.
+*/
var xmlFirstDescendantElement = function (domNode, namespaceURI, localName) {
- /// <summary>Returns the first descendant DOM element under the specified DOM node that matches the specified namespace URI and local name.</summary>
- /// <param name="domNode">DOM node from which the descendant DOM element is going to be retrieved.</param>
- /// <param name="namespaceURI" type="String" optional="true">The namespace URI of the element to match.</param>
- /// <param name="localName" type="String" optional="true">Name of the element to match.</param>
- /// <returns>The node's first descendant DOM element that matches the specified namespace URI and local name; null otherwise.</returns>
-
if (domNode.getElementsByTagNameNS) {
var result = domNode.getElementsByTagNameNS(namespaceURI, localName);
return result.length > 0 ? result[0] : null;
@@ -382,16 +383,16 @@ var xmlFirstDescendantElement = function (domNode, namespaceURI, localName) {
return xmlFirstElementMaybeRecursive(domNode, namespaceURI, localName, /*recursive*/true);
};
+/** Returns the first descendant DOM element under the specified DOM node that matches the specified namespace URI and local name.
+ * @param domNode - DOM node from which the descendant DOM element is going to be retrieved.
+ * @param {String} [namespaceURI] -
+ * @param {String} [localName] -
+ * @param {Boolean} recursive
+ * - True if the search should include all the descendants of the DOM node.
+ * - False if the search should be scoped only to the direct children of the DOM node.
+ * @return The node's first descendant DOM element that matches the specified namespace URI and local name; null otherwise.
+ */
var xmlFirstElementMaybeRecursive = function (domNode, namespaceURI, localName, recursive) {
- /// <summary>Returns the first descendant DOM element under the specified DOM node that matches the specified namespace URI and local name.</summary>
- /// <param name="domNode">DOM node from which the descendant DOM element is going to be retrieved.</param>
- /// <param name="namespaceURI" type="String" optional="true">The namespace URI of the element to match.</param>
- /// <param name="localName" type="String" optional="true">Name of the element to match.</param>
- /// <param name="recursive" type="Boolean">
- /// True if the search should include all the descendants of the DOM node.
- /// False if the search should be scoped only to the direct children of the DOM node.
- /// </param>
- /// <returns>The node's first descendant DOM element that matches the specified namespace URI and local name; null otherwise.</returns>
var firstElement = null;
xmlTraverse(domNode, recursive, function (child) {
@@ -408,10 +409,11 @@ var xmlFirstElementMaybeRecursive = function (domNode, namespaceURI, localName,
return firstElement;
};
+/** Gets the concatenated value of all immediate child text and CDATA nodes for the specified element.
+ * @param domElement - Element to get values for.
+ * @returns {String} Text for all direct children.
+ */
var xmlInnerText = function (xmlElement) {
- /// <summary>Gets the concatenated value of all immediate child text and CDATA nodes for the specified element.</summary>
- /// <param name="domElement">Element to get values for.</param>
- /// <returns type="String">Text for all direct children.</returns>
var result = null;
var root = (xmlElement.nodeType === 9 && xmlElement.documentElement) ? xmlElement.documentElement : xmlElement;
@@ -454,26 +456,29 @@ var xmlInnerText = function (xmlElement) {
return result;
};
+/** Returns the localName of a XML node.
+ * @param domNode - DOM node to get the value from.
+ * @returns {String} localName of domNode.
+ */
var xmlLocalName = function (domNode) {
- /// <summary>Returns the localName of a XML node.</summary>
- /// <param name="domNode">DOM node to get the value from.</param>
- /// <returns type="String">localName of domNode.</returns>
return domNode.localName || domNode.baseName;
};
+/** Returns the namespace URI of a XML node.
+ * @param node - DOM node to get the value from.
+ * @returns {String} Namespace URI of domNode.
+ */
var xmlNamespaceURI = function (domNode) {
- /// <summary>Returns the namespace URI of a XML node.</summary>
- /// <param name="node">DOM node to get the value from.</param>
- /// <returns type="String">Namespace URI of domNode.</returns>
return domNode.namespaceURI || null;
};
+/** Returns the value or the inner text of a XML node.
+ * @param node - DOM node to get the value from.
+ * @return Value of the domNode or the inner text if domNode represents a DOM element node.
+ */
var xmlNodeValue = function (domNode) {
- /// <summary>Returns the value or the inner text of a XML node.</summary>
- /// <param name="node">DOM node to get the value from.</param>
- /// <returns>Value of the domNode or the inner text if domNode represents a DOM element node.</returns>
if (domNode.nodeType === 1) {
return xmlInnerText(domNode);
@@ -481,14 +486,14 @@ var xmlNodeValue = function (domNode) {
return domNode.nodeValue;
};
+/** Walks through the descendants of the domNode and invokes a callback for each node.
+ * @param domNode - DOM node whose descendants are going to be traversed.
+ * @param {Boolean} recursive
+ * - True if the traversal should include all the descenants of the DOM node.
+ * - False if the traversal should be scoped only to the direct children of the DOM node.
+ * @returns {String} Namespace URI of node.
+ */
var xmlTraverse = function (domNode, recursive, onChildCallback) {
- /// <summary>Walks through the descendants of the domNode and invokes a callback for each node.</summary>
- /// <param name="domNode">DOM node whose descendants are going to be traversed.</param>
- /// <param name="recursive" type="Boolean">
- /// True if the traversal should include all the descenants of the DOM node.
- /// False if the traversal should be scoped only to the direct children of the DOM node.
- /// </param>
- /// <returns type="String">Namespace URI of node.</returns>
var subtrees = [];
var child = domNode.firstChild;
@@ -504,12 +509,13 @@ var xmlTraverse = function (domNode, recursive, onChildCallback) {
}
};
+/** Returns the next sibling DOM element of the specified DOM node.
+ * @param domNode - DOM node from which the next sibling is going to be retrieved.
+ * @param {String} [namespaceURI] -
+ * @param {String} [localName] -
+ * @return The node's next sibling DOM element, null if there is none.</returns>
+ */
var xmlSiblingElement = function (domNode, namespaceURI, localName) {
- /// <summary>Returns the next sibling DOM element of the specified DOM node.</summary>
- /// <param name="domNode">DOM node from which the next sibling is going to be retrieved.</param>
- /// <param name="namespaceURI" type="String" optional="true">The namespace URI of the element to match.</param>
- /// <param name="localName" type="String" optional="true">Name of the element to match.</param>
- /// <returns>The node's next sibling DOM element, null if there is none.</returns>
var sibling = domNode.nextSibling;
while (sibling) {
@@ -526,17 +532,18 @@ var xmlSiblingElement = function (domNode, namespaceURI, localName) {
return null;
};
+/** Creates a new empty DOM document node.
+ * @return New DOM document node.</returns>
+ *
+ * This function will first try to create a native DOM document using
+ * the browsers createDocument function. If the browser doesn't
+ * support this but supports ActiveXObject, then an attempt to create
+ * an MSXML 6.0 DOM will be made. If this attempt fails too, then an attempt
+ * for creating an MXSML 3.0 DOM will be made. If this last attemp fails or
+ * the browser doesn't support ActiveXObject then an exception will be thrown.
+ */
var xmlDom = function () {
- /// <summary>Creates a new empty DOM document node.</summary>
- /// <returns>New DOM document node.</returns>
- /// <remarks>
- /// This function will first try to create a native DOM document using
- /// the browsers createDocument function. If the browser doesn't
- /// support this but supports ActiveXObject, then an attempt to create
- /// an MSXML 6.0 DOM will be made. If this attempt fails too, then an attempt
- /// for creating an MXSML 3.0 DOM will be made. If this last attemp fails or
- /// the browser doesn't support ActiveXObject then an exception will be thrown.
- /// </remarks>
+
var implementation = window.document.implementation;
return (implementation && implementation.createDocument) ?
@@ -544,16 +551,14 @@ var xmlDom = function () {
msXmlDom();
};
+/** Appends a collection of child nodes or string values to a parent DOM node.
+ * @param parent - DOM node to which the children will be appended.
+ * @param {Array} children - Array containing DOM nodes or string values that will be appended to the parent.
+ * @return The parent with the appended children or string values.</returns>
+ * If a value in the children collection is a string, then a new DOM text node is going to be created
+ * for it and then appended to the parent.
+ */
var xmlAppendChildren = function (parent, children) {
- /// <summary>Appends a collection of child nodes or string values to a parent DOM node.</summary>
- /// <param name="parent">DOM node to which the children will be appended.</param>
- /// <param name="children" type="Array">Array containing DOM nodes or string values that will be appended to the parent.</param>
- /// <returns>The parent with the appended children or string values.</returns>
- /// <remarks>
- /// If a value in the children collection is a string, then a new DOM text node is going to be created
- /// for it and then appended to the parent.
- /// </remarks>
-
if (!isArray(children)) {
return xmlAppendChild(parent, children);
}
@@ -565,15 +570,14 @@ var xmlAppendChildren = function (parent, children) {
return parent;
};
+/** Appends a child node or a string value to a parent DOM node.
+ * @param parent - DOM node to which the child will be appended.
+ * @param child - Child DOM node or string value to append to the parent.
+ * @return The parent with the appended child or string value.</returns>
+ * If child is a string value, then a new DOM text node is going to be created
+ * for it and then appended to the parent.
+ */
var xmlAppendChild = function (parent, child) {
- /// <summary>Appends a child node or a string value to a parent DOM node.</summary>
- /// <param name="parent">DOM node to which the child will be appended.</param>
- /// <param name="child">Child DOM node or string value to append to the parent.</param>
- /// <returns>The parent with the appended child or string value.</returns>
- /// <remarks>
- /// If child is a string value, then a new DOM text node is going to be created
- /// for it and then appended to the parent.
- /// </remarks>
djsassert(parent !== child, "xmlAppendChild() - parent and child are one and the same!");
if (child) {
@@ -589,12 +593,13 @@ var xmlAppendChild = function (parent, child) {
return parent;
};
+/** Creates a new DOM attribute node.
+ * @param dom - DOM document used to create the attribute.
+ * @param {String} prefix - Namespace prefix.
+ * @param {String} namespaceURI - Namespace URI.
+ * @return DOM attribute node for the namespace declaration.
+ */
var xmlNewAttribute = function (dom, namespaceURI, qualifiedName, value) {
- /// <summary>Creates a new DOM attribute node.</summary>
- /// <param name="dom">DOM document used to create the attribute.</param>
- /// <param name="prefix" type="String">Namespace prefix.</param>
- /// <param name="namespaceURI" type="String">Namespace URI.</param>
- /// <returns>DOM attribute node for the namespace declaration.</returns>
var attribute =
dom.createAttributeNS && dom.createAttributeNS(namespaceURI, qualifiedName) ||
@@ -604,20 +609,16 @@ var xmlNewAttribute = function (dom, namespaceURI, qualifiedName, value) {
return attribute;
};
+/** Creates a new DOM element node.
+ * @param dom - DOM document used to create the DOM element.
+ * @param {String} namespaceURI - Namespace URI of the new DOM element.
+ * @param {String} qualifiedName - Qualified name in the form of "prefix:name" of the new DOM element.
+ * @param {Array} [children] Collection of child DOM nodes or string values that are going to be appended to the new DOM element.
+ * @return New DOM element.</returns>
+ * If a value in the children collection is a string, then a new DOM text node is going to be created
+ * for it and then appended to the new DOM element.
+ */
var xmlNewElement = function (dom, nampespaceURI, qualifiedName, children) {
- /// <summary>Creates a new DOM element node.</summary>
- /// <param name="dom">DOM document used to create the DOM element.</param>
- /// <param name="namespaceURI" type="String">Namespace URI of the new DOM element.</param>
- /// <param name="qualifiedName" type="String">Qualified name in the form of "prefix:name" of the new DOM element.</param>
- /// <param name="children" type="Array" optional="true">
- /// Collection of child DOM nodes or string values that are going to be appended to the new DOM element.
- /// </param>
- /// <returns>New DOM element.</returns>
- /// <remarks>
- /// If a value in the children collection is a string, then a new DOM text node is going to be created
- /// for it and then appended to the new DOM element.
- /// </remarks>
-
var element =
dom.createElementNS && dom.createElementNS(nampespaceURI, qualifiedName) ||
dom.createNode(1, qualifiedName, nampespaceURI || undefined);
@@ -625,21 +626,22 @@ var xmlNewElement = function (dom, nampespaceURI, qualifiedName, children) {
return xmlAppendChildren(element, children || []);
};
+/** Creates a namespace declaration attribute.
+ * @param dom - DOM document used to create the attribute.
+ * @param {String} namespaceURI - Namespace URI.
+ * @param {String} prefix - Namespace prefix.
+ * @return DOM attribute node for the namespace declaration.</returns>
+ */
var xmlNewNSDeclaration = function (dom, namespaceURI, prefix) {
- /// <summary>Creates a namespace declaration attribute.</summary>
- /// <param name="dom">DOM document used to create the attribute.</param>
- /// <param name="namespaceURI" type="String">Namespace URI.</param>
- /// <param name="prefix" type="String">Namespace prefix.</param>
- /// <returns>DOM attribute node for the namespace declaration.</returns>
-
return xmlNewAttribute(dom, xmlnsNS, xmlQualifiedName("xmlns", prefix), namespaceURI);
};
+/** Creates a new DOM document fragment node for the specified xml text.
+ * @param dom - DOM document from which the fragment node is going to be created.
+ * @param {String} text XML text to be represented by the XmlFragment.
+ * @return New DOM document fragment object.
+ */
var xmlNewFragment = function (dom, text) {
- /// <summary>Creates a new DOM document fragment node for the specified xml text.</summary>
- /// <param name="dom">DOM document from which the fragment node is going to be created.</param>
- /// <param name="text" type="String" mayBeNull="false">XML text to be represented by the XmlFragment.</param>
- /// <returns>New DOM document fragment object.</returns>
var value = "<c>" + text + "</c>";
var tempDom = xmlParse(value);
@@ -655,31 +657,29 @@ var xmlNewFragment = function (dom, text) {
return fragment;
};
+/** Creates new DOM text node.
+ * @param dom - DOM document used to create the text node.
+ * @param {String} text - Text value for the DOM text node.
+ * @return DOM text node.</returns>
+ */
var xmlNewText = function (dom, text) {
- /// <summary>Creates new DOM text node.</summary>
- /// <param name="dom">DOM document used to create the text node.</param>
- /// <param name="text" type="String">Text value for the DOM text node.</param>
- /// <returns>DOM text node.</returns>
-
return dom.createTextNode(text);
};
-var xmlNewNodeByPath = function (dom, root, namespaceURI, prefix, path) {
- /// <summary>Creates a new DOM element or DOM attribute node as specified by path and appends it to the DOM tree pointed by root.</summary>
- /// <param name="dom">DOM document used to create the new node.</param>
- /// <param name="root">DOM element node used as root of the subtree on which the new nodes are going to be created.</param>
- /// <param name="namespaceURI" type="String">Namespace URI of the new DOM element or attribute.</param>
- /// <param name="namespacePrefix" type="String">Prefix used to qualify the name of the new DOM element or attribute.</param>
- /// <param name="Path" type="String">Path string describing the location of the new DOM element or attribute from the root element.</param>
- /// <returns>DOM element or attribute node for the last segment of the path.</returns>
- /// <remarks>
- /// This function will traverse the path and will create a new DOM element with the specified namespace URI and prefix
- /// for each segment that doesn't have a matching element under root.
- ///
- /// The last segment of the path may be decorated with a starting @ character. In this case a new DOM attribute node
- /// will be created.
- /// </remarks>
+/** Creates a new DOM element or DOM attribute node as specified by path and appends it to the DOM tree pointed by root.
+ * @param dom - DOM document used to create the new node.
+ * @param root - DOM element node used as root of the subtree on which the new nodes are going to be created.
+ * @param {String} namespaceURI - Namespace URI of the new DOM element or attribute.
+ * @param {String} namespacePrefix - Prefix used to qualify the name of the new DOM element or attribute.
+ * @param {String} Path - Path string describing the location of the new DOM element or attribute from the root element.
+ * @return DOM element or attribute node for the last segment of the path.</returns>
+ * This function will traverse the path and will create a new DOM element with the specified namespace URI and prefix
+ * for each segment that doesn't have a matching element under root.
+ * The last segment of the path may be decorated with a starting @ character. In this case a new DOM attribute node
+ * will be created.
+ */
+var xmlNewNodeByPath = function (dom, root, namespaceURI, prefix, path) {
var name = "";
var parts = path.split("/");
var xmlFindNode = xmlFirstChildElement;
@@ -705,13 +705,11 @@ var xmlNewNodeByPath = function (dom, root, namespaceURI, prefix, path) {
return xmlNode;
};
+/** Returns the text representation of the document to which the specified node belongs.
+ * @param root - Wrapped element in the document to serialize.
+ * @returns {String} Serialized document.
+*/
var xmlSerialize = function (domNode) {
- /// <summary>
- /// Returns the text representation of the document to which the specified node belongs.
- /// </summary>
- /// <param name="root">Wrapped element in the document to serialize.</param>
- /// <returns type="String">Serialized document.</returns>
-
var xmlSerializer = window.XMLSerializer;
if (xmlSerializer) {
var serializer = new xmlSerializer();
@@ -725,11 +723,11 @@ var xmlSerialize = function (domNode) {
throw { message: "XML serialization unsupported" };
};
+/** Returns the XML representation of the all the descendants of the node.
+ * @param domNode - Node to serialize.</param>
+ * @returns {String} The XML representation of all the descendants of the node.
+ */
var xmlSerializeDescendants = function (domNode) {
- /// <summary>Returns the XML representation of the all the descendants of the node.</summary>
- /// <param name="domNode" optional="false" mayBeNull="false">Node to serialize.</param>
- /// <returns type="String">The XML representation of all the descendants of the node.</returns>
-
var children = domNode.childNodes;
var i, len = children.length;
if (len === 0) {
@@ -762,10 +760,11 @@ var xmlSerializeDescendants = function (domNode) {
return xml;
};
+/** Returns the XML representation of the node and all its descendants.
+ * @param domNode - Node to serialize
+ * @returns {String} The XML representation of the node and all its descendants.
+ */
var xmlSerializeNode = function (domNode) {
- /// <summary>Returns the XML representation of the node and all its descendants.</summary>
- /// <param name="domNode" optional="false" mayBeNull="false">Node to serialize.</param>
- /// <returns type="String">The XML representation of the node and all its descendants.</returns>
var xml = domNode.xml;
if (xml !== undefined) {
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/odata.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/odata.js b/datajs/src/lib/odata.js
index f3ff7e7..36343fb 100644
--- a/datajs/src/lib/odata.js
+++ b/datajs/src/lib/odata.js
@@ -42,11 +42,12 @@ var metadataParser = odataMetadata.metadataParser;
var handlers = [odataJson.jsonHandler, odataHandler.textHandler];
+/** Dispatches an operation to handlers.
+ * @param {String} handlerMethod - Name of handler method to invoke.
+ * @param {Object} requestOrResponse - request/response argument for delegated call.
+ * @param {Object} context - context argument for delegated call.
+ */
var dispatchHandler = function (handlerMethod, requestOrResponse, context) {
- /// <summary>Dispatches an operation to handlers.</summary>
- /// <param name="handlerMethod" type="String">Name of handler method to invoke.</param>
- /// <param name="requestOrResponse" type="Object">request/response argument for delegated call.</param>
- /// <param name="context" type="Object">context argument for delegated call.</param>
var i, len;
for (i = 0, len = handlers.length; i < len && !handlers[i][handlerMethod](requestOrResponse, context); i++) {
@@ -57,9 +58,10 @@ var dispatchHandler = function (handlerMethod, requestOrResponse, context) {
}
};
+/** Default success handler for OData.
+ * @param data - Data to process.
+ */
exports.defaultSuccess = function (data) {
- /// <summary>Default success handler for OData.</summary>
- /// <param name="data">Data to process.</param>
window.alert(window.JSON.stringify(data));
};
@@ -67,20 +69,23 @@ exports.defaultSuccess = function (data) {
exports.defaultError = throwErrorCallback;
exports.defaultHandler = {
+
+ /** Reads the body of the specified response by delegating to JSON handlers.
+ * @param response - Response object.
+ * @param context - Operation context.
+ */
read: function (response, context) {
- /// <summary>Reads the body of the specified response by delegating to JSON handlers.</summary>
- /// <param name="response">Response object.</param>
- /// <param name="context">Operation context.</param>
if (response && assigned(response.body) && response.headers["Content-Type"]) {
dispatchHandler("read", response, context);
}
},
+ /** Write the body of the specified request by delegating to JSON handlers.
+ * @param request - Reques tobject.
+ * @param context - Operation context.
+ */
write: function (request, context) {
- /// <summary>Write the body of the specified request by delegating to JSON handlers.</summary>
- /// <param name="request">Reques tobject.</param>
- /// <param name="context">Operation context.</param>
dispatchHandler("write", request, context);
},
@@ -91,14 +96,15 @@ exports.defaultHandler = {
exports.defaultMetadata = []; //TODO check why is the defaultMetadata an Array? and not an Object.
+/** Reads data from the specified URL.
+ * @param urlOrRequest - URL to read data from.
+ * @param {Function} [success] -
+ * @param {Function} [error] -
+ * @param {Object} [handler] -
+ * @param {Object} [httpClient] -
+ * @param {Object} [metadata] -
+ */
exports.read = function (urlOrRequest, success, error, handler, httpClient, metadata) {
- /// <summary>Reads data from the specified URL.</summary>
- /// <param name="urlOrRequest">URL to read data from.</param>
- /// <param name="success" type="Function" optional="true">Callback for a successful read operation.</param>
- /// <param name="error" type="Function" optional="true">Callback for handling errors.</param>
- /// <param name="handler" type="Object" optional="true">Handler for data serialization.</param>
- /// <param name="httpClient" type="Object" optional="true">HTTP client layer.</param>
- /// <param name="metadata" type="Object" optional="true">Conceptual metadata for this request.</param>
var request;
if (urlOrRequest instanceof String || typeof urlOrRequest === "string") {
@@ -110,14 +116,15 @@ exports.read = function (urlOrRequest, success, error, handler, httpClient, meta
return exports.request(request, success, error, handler, httpClient, metadata);
};
+/** Sends a request containing OData payload to a server.
+ * @param {Object} request - Object that represents the request to be sent.
+ * @param {Function} [success] -
+ * @param {Function} [error] -
+ * @param {Object} [handler] -
+ * @param {Object} [httpClient] -
+ * @param {Object} [metadata] -
+ */
exports.request = function (request, success, error, handler, httpClient, metadata) {
- /// <summary>Sends a request containing OData payload to a server.</summary>
- /// <param name="request" type="Object">Object that represents the request to be sent.</param>
- /// <param name="success" type="Function" optional="true">Callback for a successful read operation.</param>
- /// <param name="error" type="Function" optional="true">Callback for handling errors.</param>
- /// <param name="handler" type="Object" optional="true">Handler for data serialization.</param>
- /// <param name="httpClient" type="Object" optional="true">HTTP client layer.</param>
- /// <param name="metadata" type="Object" optional="true">Conceptual metadata for this request.</param>
success = success || exports.defaultSuccess;
error = error || exports.defaultError;
@@ -155,10 +162,11 @@ exports.request = function (request, success, error, handler, httpClient, metada
};
+/** Parses the csdl metadata to DataJS metatdata format. This method can be used when the metadata is retrieved using something other than DataJS
+ * @param {string} csdlMetadata - A string that represents the entire csdl metadata.
+ * @returns {Object} An object that has the representation of the metadata in Datajs format.
+ */
exports.parseMetadata = function (csdlMetadataDocument) {
- /// <summary>Parses the csdl metadata to DataJS metatdata format. This method can be used when the metadata is retrieved using something other than DataJS</summary>
- /// <param name="csdlMetadata" type="string">A string that represents the entire csdl metadata.</param>
- /// <returns type="Object">An object that has the representation of the metadata in Datajs format.</returns>
return metadataParser(null, csdlMetadataDocument);
};
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/odata/batch.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/odata/batch.js b/datajs/src/lib/odata/batch.js
index d5e82ba..a6d850e 100644
--- a/datajs/src/lib/odata/batch.js
+++ b/datajs/src/lib/odata/batch.js
@@ -45,63 +45,60 @@ var batchMediaType = "multipart/mixed";
var responseStatusRegex = /^HTTP\/1\.\d (\d{3}) (.*)$/i;
var responseHeaderRegex = /^([^()<>@,;:\\"\/[\]?={} \t]+)\s?:\s?(.*)/;
+/* Calculates a random 16 bit number and returns it in hexadecimal format.
+ * @returns {String} A 16-bit number in hex format.
+ */
var hex16 = function () {
- /// <summary>
- /// Calculates a random 16 bit number and returns it in hexadecimal format.
- /// </summary>
- /// <returns type="String">A 16-bit number in hex format.</returns>
return Math.floor((1 + Math.random()) * 0x10000).toString(16).substr(1);
};
+/* Creates a string that can be used as a multipart request boundary.
+ * @param {String} [prefix] -
+ * @returns {String} Boundary string of the format: <prefix><hex16>-<hex16>-<hex16>
+ */
var createBoundary = function (prefix) {
- /// <summary>
- /// Creates a string that can be used as a multipart request boundary.
- /// </summary>
- /// <param name="prefix" type="String" optional="true">String to use as the start of the boundary string</param>
- /// <returns type="String">Boundary string of the format: <prefix><hex16>-<hex16>-<hex16></returns>
return prefix + hex16() + "-" + hex16() + "-" + hex16();
};
+/* Gets the handler for data serialization of individual requests / responses in a batch.
+ * @param context - Context used for data serialization.
+ * @returns Handler object
+ */
var partHandler = function (context) {
- /// <summary>
- /// Gets the handler for data serialization of individual requests / responses in a batch.
- /// </summary>
- /// <param name="context">Context used for data serialization.</param>
- /// <returns>Handler object.</returns>
return context.handler.partHandler;
};
+/* Gets the current boundary used for parsing the body of a multipart response.
+ * @param context - Context used for parsing a multipart response.
+ * @returns {String} Boundary string.
+ */
var currentBoundary = function (context) {
- /// <summary>
- /// Gets the current boundary used for parsing the body of a multipart response.
- /// </summary>
- /// <param name="context">Context used for parsing a multipart response.</param>
- /// <returns type="String">Boundary string.</returns>
-
var boundaries = context.boundaries;
return boundaries[boundaries.length - 1];
};
+/** Parses a batch response.
+ * @param handler - This handler.
+ * @param {String} text - Batch text.
+ * @param {Object} context - Object with parsing context.
+ * @return An object representation of the batch.
+ */
var batchParser = function (handler, text, context) {
- /// <summary>Parses a batch response.</summary>
- /// <param name="handler">This handler.</param>
- /// <param name="text" type="String">Batch text.</param>
- /// <param name="context" type="Object">Object with parsing context.</param>
- /// <returns>An object representation of the batch.</returns>
var boundary = context.contentType.properties["boundary"];
return { __batchResponses: readBatch(text, { boundaries: [boundary], handlerContext: context }) };
};
+/** Serializes a batch object representation into text.
+ * @param handler - This handler.
+ * @param {Object} data - Representation of a batch.
+ * @param {Object} context - Object with parsing context.
+ * @return An text representation of the batch object; undefined if not applicable.#
+ */
var batchSerializer = function (handler, data, context) {
- /// <summary>Serializes a batch object representation into text.</summary>
- /// <param name="handler">This handler.</param>
- /// <param name="data" type="Object">Representation of a batch.</param>
- /// <param name="context" type="Object">Object with parsing context.</param>
- /// <returns>An text representation of the batch object; undefined if not applicable.</returns>
var cType = context.contentType = context.contentType || contentType(batchMediaType);
if (cType.mediaType === batchMediaType) {
@@ -109,14 +106,12 @@ var batchSerializer = function (handler, data, context) {
}
};
+/* Parses a multipart/mixed response body from from the position defined by the context.
+ * @param {String} text - Body of the multipart/mixed response.
+ * @param context - Context used for parsing.
+ * @return Array of objects representing the individual responses.
+ */
var readBatch = function (text, context) {
- /// <summary>
- /// Parses a multipart/mixed response body from from the position defined by the context.
- /// </summary>
- /// <param name="text" type="String" optional="false">Body of the multipart/mixed response.</param>
- /// <param name="context">Context used for parsing.</param>
- /// <returns>Array of objects representing the individual responses.</returns>
-
var delimiter = "--" + currentBoundary(context);
// Move beyond the delimiter and read the complete batch
@@ -175,17 +170,13 @@ var readBatch = function (text, context) {
return responses;
};
+/* Parses the http headers in the text from the position defined by the context.
+* @param {String} text - Text containing an http response's headers</param>
+* @param context - Context used for parsing.
+* @returns Object containing the headers as key value pairs.
+* This function doesn't support split headers and it will stop reading when it hits two consecutive line breaks.
+*/
var readHeaders = function (text, context) {
- /// <summary>
- /// Parses the http headers in the text from the position defined by the context.
- /// </summary>
- /// <param name="text" type="String" optional="false">Text containing an http response's headers</param>
- /// <param name="context">Context used for parsing.</param>
- /// <returns>Object containing the headers as key value pairs.</returns>
- /// <remarks>
- /// This function doesn't support split headers and it will stop reading when it hits two consecutive line breaks.
- /// </remarks>
-
var headers = {};
var parts;
var line;
@@ -208,15 +199,13 @@ var readHeaders = function (text, context) {
return headers;
};
+/* Parses an HTTP response.
+ * @param {String} text -Text representing the http response.
+ * @param context optional - Context used for parsing.
+ * @param {String} delimiter -String used as delimiter of the multipart response parts.
+ * @return Object representing the http response.
+ */
var readResponse = function (text, context, delimiter) {
- /// <summary>
- /// Parses an HTTP response.
- /// </summary>
- /// <param name="text" type="String" optional="false">Text representing the http response.</param>
- /// <param name="context" optional="false">Context used for parsing.</param>
- /// <param name="delimiter" type="String" optional="false">String used as delimiter of the multipart response parts.</param>
- /// <returns>Object representing the http response.</returns>
-
// Read the status line.
var pos = context.position;
var match = responseStatusRegex.exec(readLine(text, context));
@@ -242,26 +231,23 @@ var readResponse = function (text, context, delimiter) {
};
};
+/** Returns a substring from the position defined by the context up to the next line break (CRLF).
+ * @param {String} text - Input string.
+ * @param context - Context used for reading the input string.
+ * @returns {String} Substring to the first ocurrence of a line break or null if none can be found.
+ */
var readLine = function (text, context) {
- /// <summary>
- /// Returns a substring from the position defined by the context up to the next line break (CRLF).
- /// </summary>
- /// <param name="text" type="String" optional="false">Input string.</param>
- /// <param name="context" optional="false">Context used for reading the input string.</param>
- /// <returns type="String">Substring to the first ocurrence of a line break or null if none can be found. </returns>
return readTo(text, context, "\r\n");
};
+/** Returns a substring from the position given by the context up to value defined by the str parameter and increments the position in the context.
+ * @param {String} text - Input string.</param>
+ * @param context - Context used for reading the input string.</param>
+ * @param {String} [str] - Substring to read up to.
+ * @returns {String} Substring to the first ocurrence of str or the end of the input string if str is not specified. Null if the marker is not found.
+ */
var readTo = function (text, context, str) {
- /// <summary>
- /// Returns a substring from the position given by the context up to value defined by the str parameter and increments the position in the context.
- /// </summary>
- /// <param name="text" type="String" optional="false">Input string.</param>
- /// <param name="context" type="Object" optional="false">Context used for reading the input string.</param>
- /// <param name="str" type="String" optional="true">Substring to read up to.</param>
- /// <returns type="String">Substring to the first ocurrence of str or the end of the input string if str is not specified. Null if the marker is not found.</returns>
-
var start = context.position || 0;
var end = text.length;
if (str) {
@@ -277,14 +263,12 @@ var readTo = function (text, context, str) {
return text.substring(start, end);
};
+/** Serializes a batch request object to a string.
+ * @param data - Batch request object in payload representation format
+ * @param context - Context used for the serialization
+ * @returns {String} String representing the batch request
+ */
var writeBatch = function (data, context) {
- /// <summary>
- /// Serializes a batch request object to a string.
- /// </summary>
- /// <param name="data" optional="false">Batch request object in payload representation format</param>
- /// <param name="context" optional="false">Context used for the serialization</param>
- /// <returns type="String">String representing the batch request</returns>
-
if (!isBatch(data)) {
throw { message: "Data is not a batch object." };
}
@@ -306,14 +290,12 @@ var writeBatch = function (data, context) {
return batch;
};
+/** Creates the delimiter that indicates that start or end of an individual request.
+ * @param {String} boundary Boundary string used to indicate the start of the request</param>
+ * @param {Boolean} close - Flag indicating that a close delimiter string should be generated
+ * @returns {String} Delimiter string
+ */
var writeBatchPartDelimiter = function (boundary, close) {
- /// <summary>
- /// Creates the delimiter that indicates that start or end of an individual request.
- /// </summary>
- /// <param name="boundary" type="String" optional="false">Boundary string used to indicate the start of the request</param>
- /// <param name="close" type="Boolean">Flag indicating that a close delimiter string should be generated</param>
- /// <returns type="String">Delimiter string</returns>
-
var result = "\r\n--" + boundary;
if (close) {
result += "--";
@@ -322,18 +304,16 @@ var writeBatchPartDelimiter = function (boundary, close) {
return result + "\r\n";
};
+/** Serializes a part of a batch request to a string. A part can be either a GET request or
+ * a change set grouping several CUD (create, update, delete) requests.
+ * @param part - Request or change set object in payload representation format</param>
+ * @param context - Object containing context information used for the serialization</param>
+ * @param {boolean} [nested] -
+ * @returns {String} String representing the serialized part
+ * A change set is an array of request objects and they cannot be nested inside other change sets.
+ */
var writeBatchPart = function (part, context, nested) {
- /// <summary>
- /// Serializes a part of a batch request to a string. A part can be either a GET request or
- /// a change set grouping several CUD (create, update, delete) requests.
- /// </summary>
- /// <param name="part" optional="false">Request or change set object in payload representation format</param>
- /// <param name="context" optional="false">Object containing context information used for the serialization</param>
- /// <param name="nested" type="boolean" optional="true">Flag indicating that the part is nested inside a change set</param>
- /// <returns type="String">String representing the serialized part</returns>
- /// <remarks>
- /// A change set is an array of request objects and they cannot be nested inside other change sets.
- /// </remarks>
+
var changeSet = part.__changeRequests;
var result;
@@ -365,13 +345,11 @@ var writeBatchPart = function (part, context, nested) {
return result;
};
+/* Serializes a request object to a string.
+ * @param request - Request object to serialize</param>
+ * @returns {String} String representing the serialized request
+ */
var writeRequest = function (request) {
- /// <summary>
- /// Serializes a request object to a string.
- /// </summary>
- /// <param name="request" optional="false">Request object to serialize</param>
- /// <returns type="String">String representing the serialized request</returns>
-
var result = (request.method ? request.method : "GET") + " " + request.requestUri + " HTTP/1.1\r\n";
for (var name in request.headers) {
if (request.headers[name]) {
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/odata/handler.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/odata/handler.js b/datajs/src/lib/odata/handler.js
index 60254d7..01e368f 100644
--- a/datajs/src/lib/odata/handler.js
+++ b/datajs/src/lib/odata/handler.js
@@ -27,10 +27,11 @@ var trimString = utils.trimString;
var maxVersion = oDataUtils.maxVersion;
var MAX_DATA_SERVICE_VERSION = "4.0";
+/** Parses a string into an object with media type and properties.
+ * @param {String} str - String with media type to parse.
+ * @return null if the string is empty; an object with 'mediaType' and a 'properties' dictionary otherwise.
+ */
var contentType = function (str) {
- /// <summary>Parses a string into an object with media type and properties.</summary>
- /// <param name="str" type="String">String with media type to parse.</param>
- /// <returns>null if the string is empty; an object with 'mediaType' and a 'properties' dictionary otherwise.</returns>
if (!str) {
return null;
@@ -48,11 +49,11 @@ var contentType = function (str) {
return { mediaType: trimString(contentTypeParts[0]), properties: properties };
};
+/** Serializes an object with media type and properties dictionary into a string.
+ * @param contentType - Object with media type and properties dictionary to serialize.
+ * @return String representation of the media type object; undefined if contentType is null or undefined.</returns>
+ */
var contentTypeToString = function (contentType) {
- /// <summary>Serializes an object with media type and properties dictionary into a string.</summary>
- /// <param name="contentType">Object with media type and properties dictionary to serialize.</param>
- /// <returns>String representation of the media type object; undefined if contentType is null or undefined.</returns>
-
if (!contentType) {
return undefined;
}
@@ -65,13 +66,14 @@ var contentTypeToString = function (contentType) {
return result;
};
+/** Creates an object that is going to be used as the context for the handler's parser and serializer.
+ * @param contentType - Object with media type and properties dictionary.
+ * @param {String} dataServiceVersion - String indicating the version of the protocol to use.
+ * @param context - Operation context.
+ * @param handler - Handler object that is processing a resquest or response.
+ * @return Context object.</returns>
+ */
var createReadWriteContext = function (contentType, dataServiceVersion, context, handler) {
- /// <summary>Creates an object that is going to be used as the context for the handler's parser and serializer.</summary>
- /// <param name="contentType">Object with media type and properties dictionary.</param>
- /// <param name="dataServiceVersion" type="String">String indicating the version of the protocol to use.</param>
- /// <param name="context">Operation context.</param>
- /// <param name="handler">Handler object that is processing a resquest or response.</param>
- /// <returns>Context object.</returns>
var rwContext = {};
extend(rwContext, context);
@@ -84,11 +86,12 @@ var createReadWriteContext = function (contentType, dataServiceVersion, context,
return rwContext;
};
+/** Sets a request header's value. If the header has already a value other than undefined, null or empty string, then this method does nothing.
+ * @param request - Request object on which the header will be set.
+ * @param {String} name - Header name.
+ * @param {String} value - Header value.
+ */
var fixRequestHeader = function (request, name, value) {
- /// <summary>Sets a request header's value. If the header has already a value other than undefined, null or empty string, then this method does nothing.</summary>
- /// <param name="request">Request object on which the header will be set.</param>
- /// <param name="name" type="String">Header name.</param>
- /// <param name="value" type="String">Header value.</param>
if (!request) {
return;
}
@@ -99,13 +102,12 @@ var fixRequestHeader = function (request, name, value) {
}
};
-var fixDataServiceVersionHeader = function (request, version) {
- /// <summary>Sets the DataServiceVersion header of the request if its value is not yet defined or of a lower version.</summary>
- /// <param name="request">Request object on which the header will be set.</param>
- /// <param name="version" type="String">Version value.</param>
- /// <remarks>
- /// If the request has already a version value higher than the one supplied the this function does nothing.
- /// </remarks>
+/** Sets the DataServiceVersion header of the request if its value is not yet defined or of a lower version.
+ * @param request - Request object on which the header will be set.
+ * @param {String} version - Version value.
+ * If the request has already a version value higher than the one supplied the this function does nothing.
+ */
+var fixDataServiceVersionHeader = function (request, version) {
if (request) {
var headers = request.headers;
@@ -114,29 +116,32 @@ var fixDataServiceVersionHeader = function (request, version) {
}
};
+/** Gets the value of a request or response header.
+ * @param requestOrResponse - Object representing a request or a response.
+ * @param {String} name - Name of the header to retrieve.
+ * @returns {String} String value of the header; undefined if the header cannot be found.
+ */
var getRequestOrResponseHeader = function (requestOrResponse, name) {
- /// <summary>Gets the value of a request or response header.</summary>
- /// <param name="requestOrResponse">Object representing a request or a response.</param>
- /// <param name="name" type="String">Name of the header to retrieve.</param>
- /// <returns type="String">String value of the header; undefined if the header cannot be found.</returns>
var headers = requestOrResponse.headers;
return (headers && headers[name]) || undefined;
};
+/** Gets the value of the Content-Type header from a request or response.
+ * @param requestOrResponse - Object representing a request or a response.
+ * @returns {Object} Object with 'mediaType' and a 'properties' dictionary; null in case that the header is not found or doesn't have a value.
+ */
var getContentType = function (requestOrResponse) {
- /// <summary>Gets the value of the Content-Type header from a request or response.</summary>
- /// <param name="requestOrResponse">Object representing a request or a response.</param>
- /// <returns type="Object">Object with 'mediaType' and a 'properties' dictionary; null in case that the header is not found or doesn't have a value.</returns>
return contentType(getRequestOrResponseHeader(requestOrResponse, "Content-Type"));
};
var versionRE = /^\s?(\d+\.\d+);?.*$/;
+/** Gets the value of the DataServiceVersion header from a request or response.
+ * @param requestOrResponse - Object representing a request or a response.
+ * @returns {String} Data service version; undefined if the header cannot be found.
+ */
var getDataServiceVersion = function (requestOrResponse) {
- /// <summary>Gets the value of the DataServiceVersion header from a request or response.</summary>
- /// <param name="requestOrResponse">Object representing a request or a response.</param>
- /// <returns type="String">Data service version; undefined if the header cannot be found.</returns>
var value = getRequestOrResponseHeader(requestOrResponse, "OData-Version");
if (value) {
@@ -149,24 +154,26 @@ var getDataServiceVersion = function (requestOrResponse) {
// Fall through and return undefined.
};
+/** Checks that a handler can process a particular mime type.
+ * @param handler - Handler object that is processing a resquest or response.
+ * @param cType - Object with 'mediaType' and a 'properties' dictionary.
+ * @returns {Boolean} True if the handler can process the mime type; false otherwise.
+ *
+ * The following check isn't as strict because if cType.mediaType = application/; it will match an accept value of "application/xml";
+ * however in practice we don't not expect to see such "suffixed" mimeTypes for the handlers.
+ */
var handlerAccepts = function (handler, cType) {
- /// <summary>Checks that a handler can process a particular mime type.</summary>
- /// <param name="handler">Handler object that is processing a resquest or response.</param>
- /// <param name="cType">Object with 'mediaType' and a 'properties' dictionary.</param>
- /// <returns type="Boolean">True if the handler can process the mime type; false otherwise.</returns>
-
- // The following check isn't as strict because if cType.mediaType = application/; it will match an accept value of "application/xml";
- // however in practice we don't not expect to see such "suffixed" mimeTypes for the handlers.
return handler.accept.indexOf(cType.mediaType) >= 0;
};
+/** Invokes the parser associated with a handler for reading the payload of a HTTP response.
+ * @param handler - Handler object that is processing the response.
+ * @param {Function} parseCallback - Parser function that will process the response payload.
+ * @param response - HTTP response whose payload is going to be processed.
+ * @param context - Object used as the context for processing the response.
+ * @returns {Boolean} True if the handler processed the response payload and the response.data property was set; false otherwise.
+ */
var handlerRead = function (handler, parseCallback, response, context) {
- /// <summary>Invokes the parser associated with a handler for reading the payload of a HTTP response.</summary>
- /// <param name="handler">Handler object that is processing the response.</param>
- /// <param name="parseCallback" type="Function">Parser function that will process the response payload.</param>
- /// <param name="response">HTTP response whose payload is going to be processed.</param>
- /// <param name="context">Object used as the context for processing the response.</param>
- /// <returns type="Boolean">True if the handler processed the response payload and the response.data property was set; false otherwise.</returns>
if (!response || !response.headers) {
return false;
@@ -190,13 +197,14 @@ var handlerRead = function (handler, parseCallback, response, context) {
return false;
};
+/** Invokes the serializer associated with a handler for generating the payload of a HTTP request.
+ * @param handler - Handler object that is processing the request.
+ * @param {Function} serializeCallback - Serializer function that will generate the request payload.
+ * @param response - HTTP request whose payload is going to be generated.
+ * @param context - Object used as the context for serializing the request.
+ * @returns {Boolean} True if the handler serialized the request payload and the request.body property was set; false otherwise.
+ */
var handlerWrite = function (handler, serializeCallback, request, context) {
- /// <summary>Invokes the serializer associated with a handler for generating the payload of a HTTP request.</summary>
- /// <param name="handler">Handler object that is processing the request.</param>
- /// <param name="serializeCallback" type="Function">Serializer function that will generate the request payload.</param>
- /// <param name="response">HTTP request whose payload is going to be generated.</param>
- /// <param name="context">Object used as the context for serializing the request.</param>
- /// <returns type="Boolean">True if the handler serialized the request payload and the request.body property was set; false otherwise.</returns>
if (!request || !request.headers) {
return false;
}
@@ -222,13 +230,14 @@ var handlerWrite = function (handler, serializeCallback, request, context) {
return false;
};
+/** Creates a handler object for processing HTTP requests and responses.
+ * @param {Function} parseCallback - Parser function that will process the response payload.
+ * @param {Function} serializeCallback - Serializer function that will generate the request payload.
+ * @param {String} accept - String containing a comma separated list of the mime types that this handler can work with.
+ * @param {String} maxDataServiceVersion - String indicating the highest version of the protocol that this handler can work with.
+ * @returns {Object} Handler object.
+ */
var handler = function (parseCallback, serializeCallback, accept, maxDataServiceVersion) {
- /// <summary>Creates a handler object for processing HTTP requests and responses.</summary>
- /// <param name="parseCallback" type="Function">Parser function that will process the response payload.</param>
- /// <param name="serializeCallback" type="Function">Serializer function that will generate the request payload.</param>
- /// <param name="accept" type="String">String containing a comma separated list of the mime types that this handler can work with.</param>
- /// <param name="maxDataServiceVersion" type="String">String indicating the highest version of the protocol that this handler can work with.</param>
- /// <returns type="Object">Handler object.</returns>
return {
accept: accept,
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/odata/json.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/odata/json.js b/datajs/src/lib/odata/json.js
index 26d7a7f..61558e7 100644
--- a/datajs/src/lib/odata/json.js
+++ b/datajs/src/lib/odata/json.js
@@ -55,10 +55,6 @@ var XXXparseDateTime = oDataUtils.XXXparseDateTime;
var isPrimitiveEdmType = oDataUtils.isPrimitiveEdmType;
var isGeographyEdmType = oDataUtils.isGeographyEdmType;
var isGeometryEdmType = oDataUtils.isGeometryEdmType;
-//var parseDuration = oDataUtils.parseDuration;
-//var parseTimezone = oDataUtils.parseTimezone;
-//var payloadTypeOf = oDataUtils.payloadTypeOf;
-//var traverse = oDataUtils.traverse;
var PAYLOADTYPE_FEED = "f";
var PAYLOADTYPE_ENTRY = "e";
@@ -93,10 +89,11 @@ var jsonContentType = oDataHandler.contentType(jsonMediaType);
// look like regular forward slashes.
var jsonDateRE = /^\/Date\((-?\d+)(\+|-)?(\d+)?\)\/$/;
+/** Formats the given minutes into (+/-)hh:mm format.
+ * @param {Number} minutes - Number of minutes to format.
+ * @returns {String} The minutes in (+/-)hh:mm format.
+ */
var minutesToOffset = function (minutes) {
- /// <summary>Formats the given minutes into (+/-)hh:mm format.</summary>
- /// <param name="minutes" type="Number">Number of minutes to format.</param>
- /// <returns type="String">The minutes in (+/-)hh:mm format.</returns>
var sign;
if (minutes < 0) {
@@ -112,10 +109,11 @@ var minutesToOffset = function (minutes) {
return sign + formatNumberWidth(hours, 2) + ":" + formatNumberWidth(minutes, 2);
};
+/** Parses the JSON Date representation into a Date object.
+ * @param {String} value - String value.
+ * @returns {Date} A Date object if the value matches one; falsy otherwise.
+ */
var parseJsonDateString = function (value) {
- /// <summary>Parses the JSON Date representation into a Date object.</summary>
- /// <param name="value" type="String">String value.</param>
- /// <returns type="Date">A Date object if the value matches one; falsy otherwise.</returns>
var arr = value && jsonDateRE.exec(value);
if (arr) {
@@ -148,12 +146,13 @@ var parseJsonDateString = function (value) {
// See the history of this file for a candidate implementation of
// a 'formatJsonDateString' function.
+/** Parses a JSON OData payload.
+ * @param handler - This handler.
+ * @param text - Payload text (this parser also handles pre-parsed objects).
+ * @param {Object} context - Object with parsing context.
+ * @return An object representation of the OData payload.</returns>
+ */
var jsonParser = function (handler, text, context) {
- /// <summary>Parses a JSON OData payload.</summary>
- /// <param name="handler">This handler.</param>
- /// <param name="text">Payload text (this parser also handles pre-parsed objects).</param>
- /// <param name="context" type="Object">Object with parsing context.</param>
- /// <returns>An object representation of the OData payload.</returns>
var recognizeDates = defined(context.recognizeDates, handler.recognizeDates);
var model = context.metadata;
@@ -216,15 +215,13 @@ var addTypeColNoEdm = function(data, name, value ) {
};
+/* Adds typeinformation for String, Boolean and numerical EDM-types.
+ * The type is determined from the odata-json-format-v4.0.doc specification
+ * @param data - Date which will be extendet
+ * @param {Boolean} recognizeDates - True if strings formatted as datetime values should be treated as datetime values. False otherwise.
+ * @returns An object representation of the OData payload.
+ */
var readPayloadFull = function (data, model, recognizeDates) {
- /// <summary>Adds typeinformation for String, Boolean and numerical EDM-types.
- /// The type is determined from the odata-json-format-v4.0.doc specification
- ///</summary>
- /// <param name="data">Date which will be extendet</param>
- /// <param name="recognizeDates" type="Boolean">
- /// True if strings formatted as datetime values should be treated as datetime values. False otherwise.
- /// </param>
- /// <returns>An object representation of the OData payload.</returns>
if (utils.isObject(data)) {
for (var key in data) {
@@ -281,12 +278,13 @@ var readPayloadFull = function (data, model, recognizeDates) {
return data;
};
+/** Serializes the data by returning its string representation.
+ * @param handler - This handler.
+ * @param data - Data to serialize.
+ * @param {Object} context - Object with serialization context.
+ * @returns {String} The string representation of data.
+ */
var jsonSerializer = function (handler, data, context) {
- /// <summary>Serializes the data by returning its string representation.</summary>
- /// <param name="handler">This handler.</param>
- /// <param name="data">Data to serialize.</param>
- /// <param name="context" type="Object">Object with serialization context.</param>
- /// <returns type="String">The string representation of data.</returns>
var dataServiceVersion = context.dataServiceVersion || "4.0";
var cType = context.contentType = context.contentType || jsonContentType;
@@ -330,14 +328,15 @@ var formatJsonRequestPayload = function (data) {
return newdata;
};
+
+/** JSON replacer function for converting a value to its JSON representation.
+ * @param {Object} value - Value to convert.</param>
+ * @returns {String} JSON representation of the input value.
+ * This method is used during JSON serialization and invoked only by the JSON.stringify function.
+ * It should never be called directly.
+ */
var jsonReplacer = function (_, value) {
- /// <summary>JSON replacer function for converting a value to its JSON representation.</summary>
- /// <param value type="Object">Value to convert.</param>
- /// <returns type="String">JSON representation of the input value.</returns>
- /// <remarks>
- /// This method is used during JSON serialization and invoked only by the JSON.stringify function.
- /// It should never be called directly.
- /// </remarks>
+
if (value && value.__edmType === "Edm.Time") {
return formatDuration(value);
@@ -347,26 +346,28 @@ var jsonReplacer = function (_, value) {
};
+/** Creates an object containing information for the json payload.
+ * @param {String} kind - JSON payload kind, one of the PAYLOADTYPE_XXX constant values.
+ * @param {String} typeName - Type name of the JSON payload.
+ * @returns {Object} Object with kind and type fields.
+ */
var jsonMakePayloadInfo = function (kind, type) {
- /// <summary>Creates an object containing information for the json payload.</summary>
- /// <param name="kind" type="String">JSON payload kind, one of the PAYLOADTYPE_XXX constant values.</param>
- /// <param name="typeName" type="String">Type name of the JSON payload.</param>
- /// <returns type="Object">Object with kind and type fields.</returns>
+ /// TODO docu
/// <field name="kind" type="String">Kind of the JSON payload. One of the PAYLOADTYPE_XXX constant values.</field>
/// <field name="type" type="String">Data type of the JSON payload.</field>
return { kind: kind, type: type || null };
};
-/// <summary>Creates an object containing information for the context</summary>
-/// ...
-/// <returns type="Object">Object with type information
-/// attribute detectedPayloadKind(optional): see constants starting with PAYLOADTYPE_
-/// attribute deltaKind(optional): deltainformation, one of the following valus DELTATYPE_FEED | DELTATYPE_DELETED_ENTRY | DELTATYPE_LINK | DELTATYPE_DELETED_LINK
-/// attribute typeName(optional): name of the type
-/// attribute type(optional): object containing type information for entity- and complex-types ( null if a typeName is a primitive)
-/// </returns>
+/** Creates an object containing information for the context
+ * TODO check dou layout
+ * @returns {Object} Object with type information
+ * @returns {Object.detectedPayloadKind(optional)} see constants starting with PAYLOADTYPE_
+ * @returns {Object.deltaKind(optional)} deltainformation, one of the following valus DELTATYPE_FEED | DELTATYPE_DELETED_ENTRY | DELTATYPE_LINK | DELTATYPE_DELETED_LINK
+ * @returns {Object.typeName(optional)} name of the type
+ * @returns {Object.type(optional)} object containing type information for entity- and complex-types ( null if a typeName is a primitive)
+*/
var parseContextUriFragment = function( fragments, model ) {
var ret = {};
@@ -553,19 +554,17 @@ var parseContextUriFragment = function( fragments, model ) {
return ret;
};
+/** Infers the information describing the JSON payload from its metadata annotation, structure, and data model.
+ * @param {Object} data - Json response payload object.
+ * @param {Object} model - Object describing an OData conceptual schema.
+ * If the arguments passed to the function don't convey enough information about the payload to determine without doubt that the payload is a feed then it
+ * will try to use the payload object structure instead. If the payload looks like a feed (has value property that is an array or non-primitive values) then
+ * the function will report its kind as PAYLOADTYPE_FEED unless the inferFeedAsComplexType flag is set to true. This flag comes from the user request
+ * and allows the user to control how the library behaves with an ambigous JSON payload.
+ * @return Object with kind and type fields. Null if there is no metadata annotation or the payload info cannot be obtained..
+*/
var createPayloadInfo = function (data, model) {
- /// <summary>Infers the information describing the JSON payload from its metadata annotation, structure, and data model.</summary>
- /// <param name="data" type="Object">Json response payload object.</param>
- /// <param name="model" type="Object">Object describing an OData conceptual schema.</param>
- /// <remarks>
- /// If the arguments passed to the function don't convey enough information about the payload to determine without doubt that the payload is a feed then it
- /// will try to use the payload object structure instead. If the payload looks like a feed (has value property that is an array or non-primitive values) then
- /// the function will report its kind as PAYLOADTYPE_FEED unless the inferFeedAsComplexType flag is set to true. This flag comes from the user request
- /// and allows the user to control how the library behaves with an ambigous JSON payload.
- /// </remarks>
- /// <returns type="Object">
- /// Object with kind and type fields. Null if there is no metadata annotation or the payload info cannot be obtained..
- /// </returns>
+
var metadataUri = data[contextUrlAnnotation];
if (!metadataUri || typeof metadataUri !== "string") {
@@ -581,12 +580,13 @@ var createPayloadInfo = function (data, model) {
return parseContextUriFragment(fragment,model);
};
+/** Processe a JSON response payload with metadata-minimal
+ * @param {Object} data - Json response payload object
+ * @param {Object} model - Object describing an OData conceptual schema
+ * @param {Boolean} recognizeDates - Flag indicating whether datetime literal strings should be converted to JavaScript Date objects.
+ * @returns {Object} Object in the library's representation.
+ */
var readPayloadMinimal = function (data, model, recognizeDates) {
- /// <summary>Processe a JSON response payload with metadata-minimal</summary>
- /// <param name="data" type="Object">Json response payload object</param>
- /// <param name="model" type="Object">Object describing an OData conceptual schema</param>
- /// <param name="recognizeDates" type="Boolean">Flag indicating whether datetime literal strings should be converted to JavaScript Date objects.</param>
- /// <returns type="Object">Object in the library's representation.</returns>
if (!assigned(model) || isArray(model)) {
return data;
@@ -615,11 +615,12 @@ var readPayloadMinimal = function (data, model, recognizeDates) {
return data;
};
+/** Gets the key of an entry.
+ * @param {Object} data - JSON entry.
+ *
+ * @returns {string} Entry instance key.
+ */
var jsonGetEntryKey = function (data, entityModel) {
- /// <summary>Gets the key of an entry.</summary>
- /// <param name="data" type="Object">JSON entry.</param>
- /// <paraFrom Subject Received Size Categories
- /// <returns type="string">Entry instance key.</returns>
var entityInstanceKey;
var entityKeys = entityModel.key[0].propertyRef;
@@ -717,11 +718,12 @@ var readPayloadMinimalEntry = function (data, model, entryInfo, baseURI, recogni
return readPayloadMinimalObject(data, entryInfo, baseURI, model, recognizeDates);
};
+/** Formats a value according to Uri literal format
+ * @param value - Value to be formatted.
+ * @param type - Edm type of the value
+ * @returns {string} Value after formatting
+ */
var formatLiteral = function (value, type) {
- /// <summary>Formats a value according to Uri literal format</summary>
- /// <param name="value">Value to be formatted.</param>
- /// <param name="type">Edm type of the value</param>
- /// <returns type="string">Value after formatting</returns>
value = "" + formatRowLiteral(value, type);
value = encodeURIComponent(value.replace("'", "''"));
@@ -889,10 +891,11 @@ var isJsonSerializableProperty = function (property) {
return false;
};
+/** Determines whether a type name is a primitive type in a JSON payload.
+ * @param {String} typeName - Type name to test.
+ * @returns {Boolean} True if the type name an EDM primitive type or an OData spatial type; false otherwise.
+ */
var jsonIsPrimitiveType = function (typeName) {
- /// <summary>Determines whether a type name is a primitive type in a JSON payload.</summary>
- /// <param name="typeName" type="String">Type name to test.</param>
- /// <returns type="Boolean">True if the type name an EDM primitive type or an OData spatial type; false otherwise.</returns>
return isPrimitiveEdmType(typeName) || isGeographyEdmType(typeName) || isGeometryEdmType(typeName);
};
[3/3] git commit: [OLINGO-408] first conversion of the doc comments
Posted by ko...@apache.org.
[OLINGO-408] first conversion of the doc comments
Project: http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/repo
Commit: http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/commit/facdabac
Tree: http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/tree/facdabac
Diff: http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/diff/facdabac
Branch: refs/heads/master
Commit: facdabac53109aa88ae2beb566696e0f74c9f363
Parents: 4e1a3ba
Author: Sven Kobler <sv...@sap.com>
Authored: Fri Aug 15 09:21:59 2014 +0200
Committer: Sven Kobler <sv...@sap.com>
Committed: Fri Aug 15 09:21:59 2014 +0200
----------------------------------------------------------------------
datajs/src/lib/cache.js | 501 ++++++++++++++++++---------------
datajs/src/lib/cache/source.js | 164 ++++++-----
datajs/src/lib/datajs/deferred.js | 101 +++----
datajs/src/lib/datajs/utils.js | 214 +++++++-------
datajs/src/lib/datajs/xml.js | 473 ++++++++++++++++---------------
datajs/src/lib/odata.js | 66 +++--
datajs/src/lib/odata/batch.js | 178 +++++-------
datajs/src/lib/odata/handler.js | 127 +++++----
datajs/src/lib/odata/json.js | 153 +++++-----
datajs/src/lib/odata/metadata.js | 58 ++--
datajs/src/lib/odata/net.js | 88 +++---
datajs/src/lib/odata/utils.js | 438 +++++++++++++++-------------
datajs/src/lib/store.js | 10 +-
datajs/src/lib/store/dom.js | 164 ++++++-----
datajs/src/lib/store/indexeddb.js | 131 +++++----
datajs/src/lib/store/memory.js | 119 ++++----
16 files changed, 1564 insertions(+), 1421 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/cache.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/cache.js b/datajs/src/lib/cache.js
index 1df5a60..def628f 100644
--- a/datajs/src/lib/cache.js
+++ b/datajs/src/lib/cache.js
@@ -19,7 +19,11 @@
/** @module cache */
-var utils = require('./datajs.js').utils;
+var datajs = require('./datajs.js');
+var utils = datajs.utils;
+var deferred = datajs.deferred;
+var storeReq = datajs.store;
+var cacheSource = require('./cache/source');
var assigned = utils.assigned;
@@ -31,23 +35,25 @@ var normalizeURI = utils.normalizeURI;
var parseInt10 = utils.parseInt10;
var undefinedDefault = utils.undefinedDefault;
-var deferred = require('./datajs/deferred.js');
-
var createDeferred = deferred.createDeferred;
var DjsDeferred = deferred.DjsDeferred;
-var ODataCacheSource = require('./cache/source').ODataCacheSource;
+
var getJsonValueArraryLength = utils.getJsonValueArraryLength;
var sliceJsonValueArray = utils.sliceJsonValueArray;
var concatJsonValueArray = utils.concatJsonValueArray;
-var storeReq = require('./datajs.js').store;
-/** Appending a page appendPage */
+
+/** Appends a page's data to the operation data.
+ * @param {Object} operation - Operation with (i)ndex, (c)ount and (d)ata.
+ * @param {Object.i} operation - Operation <br>with
+ * (i)ndex, (c)ount and (d)ata1.
+ * @param {Object.c} operation - Operation with (i)ndex, (c)ount and (d)ata.
+ * @param {Object.d} operation - Operation with (i)ndex, (c)ount and (d)ata.
+ * @param {Object} page - Page with (i)ndex, (c)ount and (d)ata.
+ */
var appendPage = function (operation, page) {
- /// <summary>Appends a page's data to the operation data.</summary>
- /// <param name="operation" type="Object">Operation with (i)ndex, (c)ount and (d)ata.</param>
- /// <param name="page" type="Object">Page with (i)ndex, (c)ount and (d)ata.</param>
var intersection = intersectRanges(operation, page);
var start = 0;
@@ -60,11 +66,12 @@ var appendPage = function (operation, page) {
operation.d = concatJsonValueArray(operation.d, sliceJsonValueArray(page.d, start, end));
};
+/** Returns the {(i)ndex, (c)ount} range for the intersection of x and y.
+ * @param {Object} x - Range with (i)ndex and (c)ount members.
+ * @param {Object} y - Range with (i)ndex and (c)ount members.
+ * @returns {Object} The intersection (i)ndex and (c)ount; undefined if there is no intersection.
+ */
var intersectRanges = function (x, y) {
- /// <summary>Returns the {(i)ndex, (c)ount} range for the intersection of x and y.</summary>
- /// <param name="x" type="Object">Range with (i)ndex and (c)ount members.</param>
- /// <param name="y" type="Object">Range with (i)ndex and (c)ount members.</param>
- /// <returns type="Object">The intersection (i)ndex and (c)ount; undefined if there is no intersection.</returns>
var xLast = x.i + x.c;
var yLast = y.i + y.c;
@@ -78,10 +85,11 @@ var intersectRanges = function (x, y) {
return result;
};
+/** Checks whether val is a defined number with value zero or greater.
+ * @param {Number} val - Value to check.
+ * @param {String} name - Parameter name to use in exception.
+ */
var checkZeroGreater = function (val, name) {
- /// <summary>Checks whether val is a defined number with value zero or greater.</summary>
- /// <param name="val" type="Number">Value to check.</param>
- /// <param name="name" type="String">Parameter name to use in exception.</param>
if (val === undefined || typeof val !== "number") {
throw { message: "'" + name + "' must be a number." };
@@ -92,10 +100,11 @@ var checkZeroGreater = function (val, name) {
}
};
+/** Checks whether val is undefined or a number with value greater than zero.
+ * @param {Number} val - Value to check.
+ * @param {String} name - Parameter name to use in exception.
+ */
var checkUndefinedGreaterThanZero = function (val, name) {
- /// <summary>Checks whether val is undefined or a number with value greater than zero.</summary>
- /// <param name="val" type="Number">Value to check.</param>
- /// <param name="name" type="String">Parameter name to use in exception.</param>
if (val !== undefined) {
if (typeof val !== "number") {
@@ -108,20 +117,22 @@ var checkUndefinedGreaterThanZero = function (val, name) {
}
};
+/** Checks whether val is undefined or a number
+ * @param {Number} val - Value to check.
+ * @param {String} name - Parameter name to use in exception.
+ */
var checkUndefinedOrNumber = function (val, name) {
- /// <summary>Checks whether val is undefined or a number</summary>
- /// <param name="val" type="Number">Value to check.</param>
- /// <param name="name" type="String">Parameter name to use in exception.</param>
if (val !== undefined && (typeof val !== "number" || isNaN(val) || !isFinite(val))) {
throw { message: "'" + name + "' must be a number." };
}
};
+/** Performs a linear search on the specified array and removes the first instance of 'item'.
+ * @param {Array} arr - Array to search.
+ * @param item - Item being sought.
+ * @returns {Boolean} Whether the item was removed.
+ */
var removeFromArray = function (arr, item) {
- /// <summary>Performs a linear search on the specified array and removes the first instance of 'item'.</summary>
- /// <param name="arr" type="Array">Array to search.</param>
- /// <param name="item">Item being sought.</param>
- /// <returns type="Boolean">Whether the item was removed.</returns>
var i, len;
for (i = 0, len = arr.length; i < len; i++) {
@@ -134,10 +145,11 @@ var removeFromArray = function (arr, item) {
return false;
};
+/** Estimates the size of an object in bytes.
+ * @param {Object} obj - Object to determine the size of.
+ * @returns {Integer} Estimated size of the object in bytes.
+ */
var estimateSize = function (obj) {
- /// <summary>Estimates the size of an object in bytes.</summary>
- /// <param name="obj" type="Object">Object to determine the size of.</param>
- /// <returns type="Integer">Estimated size of the object in bytes.</returns>
var size = 0;
var type = typeof obj;
@@ -153,12 +165,13 @@ var estimateSize = function (obj) {
return size;
};
+/** Snaps low and high indices into page sizes and returns a range.
+ * @param {Number} lowIndex - Low index to snap to a lower value.
+ * @param {Number} highIndex - High index to snap to a higher value.
+ * @param {Number} pageSize - Page size to snap to.
+ * @returns {Object} A range with (i)ndex and (c)ount of elements.
+ */
var snapToPageBoundaries = function (lowIndex, highIndex, pageSize) {
- /// <summary>Snaps low and high indices into page sizes and returns a range.</summary>
- /// <param name="lowIndex" type="Number">Low index to snap to a lower value.</param>
- /// <param name="highIndex" type="Number">High index to snap to a higher value.</param>
- /// <param name="pageSize" type="Number">Page size to snap to.</param>
- /// <returns type="Object">A range with (i)ndex and (c)ount of elements.</returns>
lowIndex = Math.floor(lowIndex / pageSize) * pageSize;
highIndex = Math.ceil((highIndex + 1) / pageSize) * pageSize;
@@ -197,16 +210,17 @@ var READ_STATE_LOCAL = "local";
var READ_STATE_SAVE = "save";
var READ_STATE_SOURCE = "source";
+/** Creates a new operation object.
+ * @param {Function} stateMachine - State machine that describes the specific behavior of the operation.
+ * @param {DjsDeferred} promise" - Promise for requested values.
+ * @param {Boolean} isCancelable - Whether this operation can be canceled or not.
+ * @param {Number} index - Index of first item requested.
+ * @param {Number} count - Count of items requested.
+ * @param {Array} data - Array with the items requested by the operation.
+ * @param {Number} pending - Total number of pending prefetch records.
+ * @returns {DataCacheOperation} A new data cache operation instance.
+ */
var DataCacheOperation = function (stateMachine, promise, isCancelable, index, count, data, pending) {
- /// <summary>Creates a new operation object.</summary>
- /// <param name="stateMachine" type="Function">State machine that describes the specific behavior of the operation.</param>
- /// <param name="promise" type ="DjsDeferred">Promise for requested values.</param>
- /// <param name="isCancelable" type ="Boolean">Whether this operation can be canceled or not.</param>
- /// <param name="index" type="Number">Index of first item requested.</param>
- /// <param name="count" type="Number">Count of items requested.</param>
- /// <param name="data" type="Array">Array with the items requested by the operation.</param>
- /// <param name="pending" type="Number">Total number of pending prefetch records.</param>
- /// <returns type="DataCacheOperation">A new data cache operation instance.</returns>
/// <field name="p" type="DjsDeferred">Promise for requested values.</field>
/// <field name="i" type="Number">Index of first item requested.</field>
@@ -231,9 +245,10 @@ var DataCacheOperation = function (stateMachine, promise, isCancelable, index, c
that.pending = pending;
that.oncomplete = null;
+ /** Transitions this operation to the cancel state and sets the canceled flag to true.
+ * The function is a no-op if the operation is non-cancelable.</summary>
+ */
that.cancel = function () {
- /// <summary>Transitions this operation to the cancel state and sets the canceled flag to true.</summary>
- /// <remarks>The function is a no-op if the operation is non-cancelable.</summary>
if (!isCancelable) {
return;
@@ -246,15 +261,17 @@ var DataCacheOperation = function (stateMachine, promise, isCancelable, index, c
}
};
+ /** Transitions this operation to the end state.
+ */
that.complete = function () {
- /// <summary>Transitions this operation to the end state.</summary>
djsassert(that.s !== OPERATION_STATE_END, "DataCacheOperation.complete() - operation is in the end state", that);
transition(OPERATION_STATE_END, stateData);
};
+ /** Transitions this operation to the error state.
+ */
that.error = function (err) {
- /// <summary>Transitions this operation to the error state.</summary>
if (!that.canceled) {
djsassert(that.s !== OPERATION_STATE_END, "DataCacheOperation.error() - operation is in the end state", that);
djsassert(that.s !== OPERATION_STATE_ERROR, "DataCacheOperation.error() - operation is in the error state", that);
@@ -262,26 +279,29 @@ var DataCacheOperation = function (stateMachine, promise, isCancelable, index, c
}
};
+ /** Executes the operation's current state in the context of a new cache state.
+ * @param {Object} state - New cache state.
+ */
that.run = function (state) {
- /// <summary>Executes the operation's current state in the context of a new cache state.</summary>
- /// <param name="state" type="Object">New cache state.</param>
cacheState = state;
that.transition(that.s, stateData);
};
+ /** Transitions this operation to the wait state.
+ */
that.wait = function (data) {
- /// <summary>Transitions this operation to the wait state.</summary>
djsassert(that.s !== OPERATION_STATE_END, "DataCacheOperation.wait() - operation is in the end state", that);
transition(OPERATION_STATE_WAIT, data);
};
+ /** State machine that describes all operations common behavior.
+ * @param {Object} opTargetState - Operation state to transition to.
+ * @param {Object} cacheState - Current cache state.
+ * @param {Object} [data] - Additional data passed to the state.
+ */
var operationStateMachine = function (opTargetState, cacheState, data) {
- /// <summary>State machine that describes all operations common behavior.</summary>
- /// <param name="opTargetState" type="Object">Operation state to transition to.</param>
- /// <param name="cacheState" type="Object">Current cache state.</param>
- /// <param name="data" type="Object" optional="true">Additional data passed to the state.</param>
switch (opTargetState) {
case OPERATION_STATE_START:
@@ -339,10 +359,11 @@ var DataCacheOperation = function (stateMachine, promise, isCancelable, index, c
}
};
+ /** Transitions this operation to a new state.
+ * @param {Object} state - State to transition the operation to.
+ * @param {Object} [data] -
+ */
var transition = function (state, data) {
- /// <summary>Transitions this operation to a new state.</summary>
- /// <param name="state" type="Object">State to transition the operation to.</param>
- /// <param name="data" type="Object" optional="true">Additional data passed to the state.</param>
that.s = state;
stateData = data;
@@ -354,8 +375,9 @@ var DataCacheOperation = function (stateMachine, promise, isCancelable, index, c
return that;
};
+/** Fires a resolved notification as necessary.
+*/
DataCacheOperation.prototype.fireResolved = function () {
- /// <summary>Fires a resolved notification as necessary.</summary>
// Fire the resolve just once.
var p = this.p;
@@ -365,8 +387,9 @@ DataCacheOperation.prototype.fireResolved = function () {
}
};
+/** Fires a rejected notification as necessary.
+*/
DataCacheOperation.prototype.fireRejected = function (reason) {
- /// <summary>Fires a rejected notification as necessary.</summary>
// Fire the rejection just once.
var p = this.p;
@@ -376,20 +399,20 @@ DataCacheOperation.prototype.fireRejected = function (reason) {
}
};
+/** Fires a canceled notification as necessary.
+*/
DataCacheOperation.prototype.fireCanceled = function () {
- /// <summary>Fires a canceled notification as necessary.</summary>
this.fireRejected({ canceled: true, message: "Operation canceled" });
};
+/** Creates a data cache for a collection that is efficiently loaded on-demand.
+ * @param options - Options for the data cache, including name, source, pageSize,
+ * prefetchSize, cacheSize, storage mechanism, and initial prefetch and local-data handler.
+ * @returns {DataCache} A new data cache instance.
+ */
var DataCache = function (options) {
- /// <summary>Creates a data cache for a collection that is efficiently loaded on-demand.</summary>
- /// <param name="options">
- /// Options for the data cache, including name, source, pageSize,
- /// prefetchSize, cacheSize, storage mechanism, and initial prefetch and local-data handler.
- /// </param>
- /// <returns type="DataCache">A new data cache instance.</returns>
var state = CACHE_STATE_INIT;
var stats = { counts: 0, netReads: 0, prefetches: 0, cacheReads: 0 };
@@ -415,7 +438,7 @@ var DataCache = function (options) {
var source = options.source;
if (typeof source === "string") {
// Create a new cache source.
- source = new ODataCacheSource(options);
+ source = new cacheSource.ODataCacheSource(options);
}
source.options = options;
@@ -427,9 +450,10 @@ var DataCache = function (options) {
that.onidle = options.idle;
that.stats = stats;
+ /** Counts the number of items in the collection.
+ * @returns {Object} A promise with the number of items.
+ */
that.count = function () {
- /// <summary>Counts the number of items in the collection.</summary>
- /// <returns type="Object">A promise with the number of items.</returns>
if (cacheFailure) {
throw cacheFailure;
@@ -458,7 +482,8 @@ var DataCache = function (options) {
return extend(deferred.promise(), {
cancel: function () {
- /// <summary>Aborts the count operation.</summary>
+ /** Aborts the count operation.
+ */
if (request) {
canceled = true;
request.abort();
@@ -468,13 +493,14 @@ var DataCache = function (options) {
});
};
+ /** Cancels all running operations and clears all local data associated with this cache.
+
+ * New read requests made while a clear operation is in progress will not be canceled.
+ * Instead they will be queued for execution once the operation is completed.
+
+ * @returns {Object} A promise that has no value and can't be canceled.
+ */
that.clear = function () {
- /// <summary>Cancels all running operations and clears all local data associated with this cache.</summary>
- /// <remarks>
- /// New read requests made while a clear operation is in progress will not be canceled.
- /// Instead they will be queued for execution once the operation is completed.
- /// </remarks>
- /// <returns type="Object">A promise that has no value and can't be canceled.</returns>
if (cacheFailure) {
throw cacheFailure;
@@ -489,42 +515,43 @@ var DataCache = function (options) {
return clearOperations[0].p;
};
+ /** Filters the cache data based a predicate.
+ * @param {Number} index - The index of the item to start filtering forward from.
+ * @param {Number} count - Maximum number of items to include in the result.
+ * @param {Function} predicate - Callback function returning a boolean that determines whether an item should be included in the result or not.
+
+ * Specifying a negative count value will yield all the items in the cache that satisfy the predicate.
+
+ * @returns {DjsDeferred} A promise for an array of results.
+ */
that.filterForward = function (index, count, predicate) {
- /// <summary>Filters the cache data based a predicate.</summary>
- /// <param name="index" type="Number">The index of the item to start filtering forward from.</param>
- /// <param name="count" type="Number">Maximum number of items to include in the result.</param>
- /// <param name="predicate" type="Function">Callback function returning a boolean that determines whether an item should be included in the result or not.</param>
- /// <remarks>
- /// Specifying a negative count value will yield all the items in the cache that satisfy the predicate.
- /// </remarks>
- /// <returns type="DjsDeferred">A promise for an array of results.</returns>
return filter(index, count, predicate, false);
};
+ /** Filters the cache data based a predicate.
+ * @param {Number} index - The index of the item to start filtering backward from.
+ * @param {Number} count - Maximum number of items to include in the result.
+ * @param {Function} predicate - Callback function returning a boolean that determines whether an item should be included in the result or not.
+
+ * Specifying a negative count value will yield all the items in the cache that satisfy the predicate.
+
+ * @returns {DjsDeferred} A promise for an array of results.
+ */
that.filterBack = function (index, count, predicate) {
- /// <summary>Filters the cache data based a predicate.</summary>
- /// <param name="index" type="Number">The index of the item to start filtering backward from.</param>
- /// <param name="count" type="Number">Maximum number of items to include in the result.</param>
- /// <param name="predicate" type="Function">Callback function returning a boolean that determines whether an item should be included in the result or not.</param>
- /// <remarks>
- /// Specifying a negative count value will yield all the items in the cache that satisfy the predicate.
- /// </remarks>
- /// <returns type="DjsDeferred">A promise for an array of results.</returns>
return filter(index, count, predicate, true);
};
+ /** Reads a range of adjacent records.
+ * @param {Number} index - Zero-based index of record range to read.
+ * @param {Number} count - Number of records in the range.
+
+ * New read requests made while a clear operation is in progress will not be canceled.
+ * Instead they will be queued for execution once the operation is completed.
+
+ * @returns {DjsDeferred} A promise for an array of records; less records may be returned if the
+ * end of the collection is found.
+ */
that.readRange = function (index, count) {
- /// <summary>Reads a range of adjacent records.</summary>
- /// <param name="index" type="Number">Zero-based index of record range to read.</param>
- /// <param name="count" type="Number">Number of records in the range.</param>
- /// <remarks>
- /// New read requests made while a clear operation is in progress will not be canceled.
- /// Instead they will be queued for execution once the operation is completed.
- /// </remarks>
- /// <returns type="DjsDeferred">
- /// A promise for an array of records; less records may be returned if the
- /// end of the collection is found.
- /// </returns>
checkZeroGreater(index, "index");
checkZeroGreater(count, "count");
@@ -541,15 +568,17 @@ var DataCache = function (options) {
return extend(deferred.promise(), {
cancel: function () {
- /// <summary>Aborts the readRange operation.</summary>
+ /** Aborts the readRange operation.
+ */
op.cancel();
}
});
};
+ /** Creates an Observable object that enumerates all the cache contents.
+ * @returns A new Observable object that enumerates all the cache contents.
+ */
that.ToObservable = that.toObservable = function () {
- /// <summary>Creates an Observable object that enumerates all the cache contents.</summary>
- /// <returns>A new Observable object that enumerates all the cache contents.</returns>
if (!window.Rx || !window.Rx.Observable) {
throw { message: "Rx library not available - include rx.js" };
}
@@ -592,14 +621,15 @@ var DataCache = function (options) {
});
};
+ /** Creates a function that handles a callback by setting the cache into failure mode.
+ * @param {String} message - Message text.
+ * @returns {Function} Function to use as error callback.
+
+ * This function will specifically handle problems with critical store resources
+ * during cache initialization.
+ */
var cacheFailureCallback = function (message) {
- /// <summary>Creates a function that handles a callback by setting the cache into failure mode.</summary>
- /// <param name="message" type="String">Message text.</param>
- /// <returns type="Function">Function to use as error callback.</returns>
- /// <remarks>
- /// This function will specifically handle problems with critical store resources
- /// during cache initialization.
- /// </remarks>
+
return function (error) {
cacheFailure = { message: message, error: error };
@@ -622,10 +652,11 @@ var DataCache = function (options) {
};
};
+ /** Updates the cache's state and signals all pending operations of the change.
+ * @param {Object} newState - New cache state.
+ * This method is a no-op if the cache's current state and the new state are the same.</remarks>
+ */
var changeState = function (newState) {
- /// <summary>Updates the cache's state and signals all pending operations of the change.</summary>
- /// <param name="newState" type="Object">New cache state.</param>
- /// <remarks>This method is a no-op if the cache's current state and the new state are the same.</remarks>
if (newState !== state) {
state = newState;
@@ -637,9 +668,10 @@ var DataCache = function (options) {
}
};
+ /** Removes all the data stored in the cache.
+ * @returns {DjsDeferred} A promise with no value.
+ */
var clearStore = function () {
- /// <summary>Removes all the data stored in the cache.</summary>
- /// <returns type="DjsDeferred">A promise with no value.</returns>
djsassert(state === CACHE_STATE_DESTROY || state === CACHE_STATE_INIT, "DataCache.clearStore() - cache is not on the destroy or initialize state, current sate = " + state);
var deferred = new DjsDeferred();
@@ -667,10 +699,11 @@ var DataCache = function (options) {
return deferred;
};
+ /** Removes an operation from the caches queues and changes the cache state to idle.
+ * @param {DataCacheOperation} operation - Operation to dequeue.
+ * This method is used as a handler for the operation's oncomplete event.</remarks>
+ */
var dequeueOperation = function (operation) {
- /// <summary>Removes an operation from the caches queues and changes the cache state to idle.</summary>
- /// <param name="operation" type="DataCacheOperation">Operation to dequeue.</param>
- /// <remarks>This method is used as a handler for the operation's oncomplete event.</remarks>
var removed = removeFromArray(clearOperations, operation);
if (!removed) {
@@ -684,10 +717,11 @@ var DataCache = function (options) {
changeState(CACHE_STATE_IDLE);
};
+ /** Requests data from the cache source.
+ * @param {Number} start - Zero-based index of items to request.
+ * @returns {DjsDeferred} A promise for a page object with (i)ndex, (c)ount, (d)ata.
+ */
var fetchPage = function (start) {
- /// <summary>Requests data from the cache source.</summary>
- /// <param name="start" type="Number">Zero-based index of items to request.</param>
- /// <returns type="DjsDeferred">A promise for a page object with (i)ndex, (c)ount, (d)ata.</returns>
djsassert(state !== CACHE_STATE_DESTROY, "DataCache.fetchPage() - cache is on the destroy state");
djsassert(state !== CACHE_STATE_IDLE, "DataCache.fetchPage() - cache is on the idle state");
@@ -714,16 +748,16 @@ var DataCache = function (options) {
});
};
+ /** Filters the cache data based a predicate.
+ * @param {Number} index - The index of the item to start filtering from.
+ * @param {Number} count - Maximum number of items to include in the result.
+ * @param {Function} predicate - Callback function returning a boolean that determines whether an item should be included in the result or not.
+ * @param {Boolean} backwards - True if the filtering should move backward from the specified index, falsey otherwise.
+ * Specifying a negative count value will yield all the items in the cache that satisfy the predicate.
+ * @returns {DjsDeferred} A promise for an array of results.
+ */
var filter = function (index, count, predicate, backwards) {
- /// <summary>Filters the cache data based a predicate.</summary>
- /// <param name="index" type="Number">The index of the item to start filtering from.</param>
- /// <param name="count" type="Number">Maximum number of items to include in the result.</param>
- /// <param name="predicate" type="Function">Callback function returning a boolean that determines whether an item should be included in the result or not.</param>
- /// <param name="backwards" type="Boolean">True if the filtering should move backward from the specified index, falsey otherwise.</param>
- /// <remarks>
- /// Specifying a negative count value will yield all the items in the cache that satisfy the predicate.
- /// </remarks>
- /// <returns type="DjsDeferred">A promise for an array of results.</returns>
+
index = parseInt10(index);
count = parseInt10(count);
@@ -790,8 +824,10 @@ var DataCache = function (options) {
readMore(initialIndex, initialCount);
return extend(deferred.promise(), {
+ /** Aborts the filter operation
+ */
cancel: function () {
- /// <summary>Aborts the filter operation</summary>
+
if (pendingReadRange) {
pendingReadRange.cancel();
}
@@ -800,24 +836,25 @@ var DataCache = function (options) {
});
};
+ /** Fires an onidle event if any functions are assigned.
+ */
var fireOnIdle = function () {
- /// <summary>Fires an onidle event if any functions are assigned.</summary>
if (that.onidle && pendingOperations === 0) {
that.onidle();
}
};
+ /** Creates and starts a new prefetch operation.
+ * @param {Number} start - Zero-based index of the items to prefetch.
+ * This method is a no-op if any of the following conditions is true:
+ * 1.- prefetchSize is 0
+ * 2.- All data has been read and stored locally in the cache.
+ * 3.- There is already an all data prefetch operation queued.
+ * 4.- The cache has run out of available space (overflowed).
+ */
var prefetch = function (start) {
- /// <summary>Creates and starts a new prefetch operation.</summary>
- /// <param name="start" type="Number">Zero-based index of the items to prefetch.</param>
- /// <remarks>
- /// This method is a no-op if any of the following conditions is true:
- /// 1.- prefetchSize is 0
- /// 2.- All data has been read and stored locally in the cache.
- /// 3.- There is already an all data prefetch operation queued.
- /// 4.- The cache has run out of available space (overflowed).
- /// <remarks>
+
if (allDataLocal || prefetchSize === 0 || overflowed) {
return;
@@ -832,10 +869,11 @@ var DataCache = function (options) {
}
};
+ /** Queues an operation and runs it.
+ * @param {DataCacheOperation} op - Operation to queue.
+ * @param {Array} queue - Array that will store the operation.
+ */
var queueAndStart = function (op, queue) {
- /// <summary>Queues an operation and runs it.</summary>
- /// <param name="op" type="DataCacheOperation">Operation to queue.</param>
- /// <param name="queue" type="Array">Array that will store the operation.</param>
op.oncomplete = dequeueOperation;
queue.push(op);
@@ -843,17 +881,18 @@ var DataCache = function (options) {
op.run(state);
};
+ /** Requests a page from the cache local store.
+ * @param {Number} key - Zero-based index of the reuqested page.
+ * @returns {DjsDeferred} A promise for a found flag and page object with (i)ndex, (c)ount, (d)ata, and (t)icks.
+ */
var readPage = function (key) {
- /// <summary>Requests a page from the cache local store.</summary>
- /// <param name="key" type="Number">Zero-based index of the reuqested page.</param>
- /// <returns type="DjsDeferred">A promise for a found flag and page object with (i)ndex, (c)ount, (d)ata, and (t)icks.</returns>
djsassert(state !== CACHE_STATE_DESTROY, "DataCache.readPage() - cache is on the destroy state");
var canceled = false;
var deferred = extend(new DjsDeferred(), {
cancel: function () {
- /// <summary>Aborts the readPage operation.</summary>
+ /** Aborts the readPage operation.*/
canceled = true;
}
});
@@ -877,11 +916,12 @@ var DataCache = function (options) {
return deferred;
};
+ /** Saves a page to the cache local store.
+ * @param {Number} key - Zero-based index of the requested page.
+ * @param {Object} page - Object with (i)ndex, (c)ount, (d)ata, and (t)icks.
+ * @returns {DjsDeferred} A promise with no value.
+ */
var savePage = function (key, page) {
- /// <summary>Saves a page to the cache local store.</summary>
- /// <param name="key" type="Number">Zero-based index of the requested page.</param>
- /// <param name="page" type="Object">Object with (i)ndex, (c)ount, (d)ata, and (t)icks.</param>
- /// <returns type="DjsDeferred">A promise with no value.</returns>
djsassert(state !== CACHE_STATE_DESTROY, "DataCache.savePage() - cache is on the destroy state");
djsassert(state !== CACHE_STATE_IDLE, "DataCache.savePage() - cache is on the idle state");
@@ -889,8 +929,9 @@ var DataCache = function (options) {
var canceled = false;
var deferred = extend(new DjsDeferred(), {
+ /** Aborts the readPage operation.
+ */
cancel: function () {
- /// <summary>Aborts the readPage operation.</summary>
canceled = true;
}
});
@@ -920,10 +961,11 @@ var DataCache = function (options) {
return deferred;
};
+ /** Saves the cache's current settings to the local store.
+ * @param {Function} success - Success callback.
+ * @param {Function} error - Errror callback.
+ */
var saveSettings = function (success, error) {
- /// <summary>Saves the cache's current settings to the local store.</summary>
- /// <param name="success" type="Function">Success callback.</param>
- /// <param name="error" type="Function">Errror callback.</param>
var settings = {
actualCacheSize: actualCacheSize,
@@ -940,14 +982,15 @@ var DataCache = function (options) {
store.addOrUpdate("__settings", settings, success, error);
};
+ /** Creates a function that handles a store error.
+ * @param {DjsDeferred} deferred - Deferred object to resolve.
+ * @param {String} message - Message text.
+ * @returns {Function} Function to use as error callback.
+
+ * This function will specifically handle problems when interacting with the store.
+ */
var storeFailureCallback = function (deferred/*, message*/) {
- /// <summary>Creates a function that handles a store error.</summary>
- /// <param name="deferred" type="DjsDeferred">Deferred object to resolve.</param>
- /// <param name="message" type="String">Message text.</param>
- /// <returns type="Function">Function to use as error callback.</returns>
- /// <remarks>
- /// This function will specifically handle problems when interacting with the store.
- /// </remarks>
+
return function (/*error*/) {
// var console = window.console;
@@ -959,10 +1002,11 @@ var DataCache = function (options) {
};
};
+ /** Updates the cache's settings based on a page object.
+ * @param {Object} page - Object with (i)ndex, (c)ount, (d)ata.
+ * @param {Number} pageBytes - Size of the page in bytes.
+ */
var updateSettings = function (page, pageBytes) {
- /// <summary>Updates the cache's settings based on a page object.</summary>
- /// <param name="page" type="Object">Object with (i)ndex, (c)ount, (d)ata.</param>
- /// <param name="pageBytes" type="Number">Size of the page in bytes.</param>
var pageCount = page.c;
var pageIndex = page.i;
@@ -989,15 +1033,16 @@ var DataCache = function (options) {
}
};
+ /** State machine describing the behavior for cancelling a read or prefetch operation.
+ * @param {DataCacheOperation} operation - Operation being run.
+ * @param {Object} opTargetState - Operation state to transition to.
+ * @param {Object} cacheState - Current cache state.
+ * @param {Object} [data] -
+
+ * This state machine contains behavior common to read and prefetch operations.
+ */
var cancelStateMachine = function (operation, opTargetState, cacheState, data) {
- /// <summary>State machine describing the behavior for cancelling a read or prefetch operation.</summary>
- /// <param name="operation" type="DataCacheOperation">Operation being run.</param>
- /// <param name="opTargetState" type="Object">Operation state to transition to.</param>
- /// <param name="cacheState" type="Object">Current cache state.</param>
- /// <param name="data" type="Object" optional="true">Additional data passed to the state.</param>
- /// <remarks>
- /// This state machine contains behavior common to read and prefetch operations.
- /// </remarks>
+
var canceled = operation.canceled && opTargetState !== OPERATION_STATE_END;
if (canceled) {
@@ -1012,15 +1057,16 @@ var DataCache = function (options) {
return canceled;
};
+ /** State machine describing the behavior of a clear operation.
+ * @param {DataCacheOperation} operation - Operation being run.
+ * @param {Object} opTargetState - Operation state to transition to.
+ * @param {Object} cacheState - Current cache state.
+
+ * Clear operations have the highest priority and can't be interrupted by other operations; however,
+ * they will preempt any other operation currently executing.
+ */
var destroyStateMachine = function (operation, opTargetState, cacheState) {
- /// <summary>State machine describing the behavior of a clear operation.</summary>
- /// <param name="operation" type="DataCacheOperation">Operation being run.</param>
- /// <param name="opTargetState" type="Object">Operation state to transition to.</param>
- /// <param name="cacheState" type="Object">Current cache state.</param>
- /// <remarks>
- /// Clear operations have the highest priority and can't be interrupted by other operations; however,
- /// they will preempt any other operation currently executing.
- /// </remarks>
+
var transition = operation.transition;
@@ -1057,20 +1103,21 @@ var DataCache = function (options) {
return true;
};
+ /** State machine describing the behavior of a prefetch operation.
+ * @param {DataCacheOperation} operation - Operation being run.
+ * @param {Object} opTargetState - Operation state to transition to.
+ * @param {Object} cacheState - Current cache state.
+ * @param {Object} [data] -
+
+ * Prefetch operations have the lowest priority and will be interrupted by operations of
+ * other kinds. A preempted prefetch operation will resume its execution only when the state
+ * of the cache returns to idle.
+ *
+ * If a clear operation starts executing then all the prefetch operations are canceled,
+ * even if they haven't started executing yet.
+ */
var prefetchStateMachine = function (operation, opTargetState, cacheState, data) {
- /// <summary>State machine describing the behavior of a prefetch operation.</summary>
- /// <param name="operation" type="DataCacheOperation">Operation being run.</param>
- /// <param name="opTargetState" type="Object">Operation state to transition to.</param>
- /// <param name="cacheState" type="Object">Current cache state.</param>
- /// <param name="data" type="Object" optional="true">Additional data passed to the state.</param>
- /// <remarks>
- /// Prefetch operations have the lowest priority and will be interrupted by operations of
- /// other kinds. A preempted prefetch operation will resume its execution only when the state
- /// of the cache returns to idle.
- ///
- /// If a clear operation starts executing then all the prefetch operations are canceled,
- /// even if they haven't started executing yet.
- /// </remarks>
+
// Handle cancelation
if (!cancelStateMachine(operation, opTargetState, cacheState, data)) {
@@ -1125,21 +1172,22 @@ var DataCache = function (options) {
return true;
};
+ /** State machine describing the behavior of a read operation.
+ * @param {DataCacheOperation} operation - Operation being run.
+ * @param {Object} opTargetState - Operation state to transition to.
+ * @param {Object} cacheState - Current cache state.
+ * @param {Object} [data] -
+
+ * Read operations have a higher priority than prefetch operations, but lower than
+ * clear operations. They will preempt any prefetch operation currently running
+ * but will be interrupted by a clear operation.
+ *
+ * If a clear operation starts executing then all the currently running
+ * read operations are canceled. Read operations that haven't started yet will
+ * wait in the start state until the destory operation finishes.
+ */
var readStateMachine = function (operation, opTargetState, cacheState, data) {
- /// <summary>State machine describing the behavior of a read operation.</summary>
- /// <param name="operation" type="DataCacheOperation">Operation being run.</param>
- /// <param name="opTargetState" type="Object">Operation state to transition to.</param>
- /// <param name="cacheState" type="Object">Current cache state.</param>
- /// <param name="data" type="Object" optional="true">Additional data passed to the state.</param>
- /// <remarks>
- /// Read operations have a higher priority than prefetch operations, but lower than
- /// clear operations. They will preempt any prefetch operation currently running
- /// but will be interrupted by a clear operation.
- ///
- /// If a clear operation starts executing then all the currently running
- /// read operations are canceled. Read operations that haven't started yet will
- /// wait in the start state until the destory operation finishes.
- /// </remarks>
+
// Handle cancelation
if (!cancelStateMachine(operation, opTargetState, cacheState, data)) {
@@ -1205,16 +1253,15 @@ var DataCache = function (options) {
return true;
};
+ /** State machine describing the behavior for reading and saving data into the cache.
+ * @param {DataCacheOperation} operation - Operation being run.
+ * @param {Object} opTargetState - Operation state to transition to.
+ * @param {Object} cacheState - Current cache state.
+ * @param {Object} [data] -
+ * @param {Boolean} isPrefetch - Flag indicating whether a read (false) or prefetch (true) operation is running.
+ * This state machine contains behavior common to read and prefetch operations.
+ */
var readSaveStateMachine = function (operation, opTargetState, cacheState, data, isPrefetch) {
- /// <summary>State machine describing the behavior for reading and saving data into the cache.</summary>
- /// <param name="operation" type="DataCacheOperation">Operation being run.</param>
- /// <param name="opTargetState" type="Object">Operation state to transition to.</param>
- /// <param name="cacheState" type="Object">Current cache state.</param>
- /// <param name="data" type="Object" optional="true">Additional data passed to the state.</param>
- /// <param name="isPrefetch" type="Boolean">Flag indicating whether a read (false) or prefetch (true) operation is running.
- /// <remarks>
- /// This state machine contains behavior common to read and prefetch operations.
- /// </remarks>
var error = operation.error;
var transition = operation.transition;
@@ -1338,13 +1385,13 @@ var DataCache = function (options) {
return that;
};
+/** Creates a data cache for a collection that is efficiently loaded on-demand.
+ * @param options
+ * Options for the data cache, including name, source, pageSize, TODO check doku
+ * prefetchSize, cacheSize, storage mechanism, and initial prefetch and local-data handler.
+ * @returns {DataCache} A new data cache instance.
+ */
exports.createDataCache = function (options) {
- /// <summary>Creates a data cache for a collection that is efficiently loaded on-demand.</summary>
- /// <param name="options">
- /// Options for the data cache, including name, source, pageSize,
- /// prefetchSize, cacheSize, storage mechanism, and initial prefetch and local-data handler.
- /// </param>
- /// <returns type="DataCache">A new data cache instance.</returns>
checkUndefinedGreaterThanZero(options.pageSize, "pageSize");
checkUndefinedOrNumber(options.cacheSize, "cacheSize");
checkUndefinedOrNumber(options.prefetchSize, "prefetchSize");
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/cache/source.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/cache/source.js b/datajs/src/lib/cache/source.js
index 0f43ac8..96c6d9e 100644
--- a/datajs/src/lib/cache/source.js
+++ b/datajs/src/lib/cache/source.js
@@ -16,6 +16,8 @@
* specific language governing permissions and limitations
* under the License.
*/
+
+ /** @module cache_source */
var utils = require("./../datajs.js").utils;
var odataRequest = require("./../odata.js");
@@ -23,19 +25,23 @@ var odataRequest = require("./../odata.js");
var parseInt10 = utils.parseInt10;
var normalizeURICase = utils.normalizeURICase;
+
+/** Appends the specified escaped query option to the specified URI.
+ * @param {String} uri - URI to append option to.
+ * @param {String} queryOption - Escaped query option to append.
+ */
var appendQueryOption = function (uri, queryOption) {
- /// <summary>Appends the specified escaped query option to the specified URI.</summary>
- /// <param name="uri" type="String">URI to append option to.</param>
- /// <param name="queryOption" type="String">Escaped query option to append.</param>
var separator = (uri.indexOf("?") >= 0) ? "&" : "?";
return uri + separator + queryOption;
};
+/** Appends the specified segment to the given URI.
+ * @param {String} uri - URI to append a segment to.
+ * @param {String} segment - Segment to append.
+ * @returns {String} The original URI with a new segment appended.
+ */
var appendSegment = function (uri, segment) {
- /// <summary>Appends the specified segment to the given URI.</summary>
- /// <param name="uri" type="String">URI to append a segment to.</param>
- /// <param name="segment" type="String">Segment to append.</param>
- /// <returns type="String">The original URI with a new segment appended.</returns>
+
var index = uri.indexOf("?");
var queryPortion = "";
@@ -50,11 +56,12 @@ var appendSegment = function (uri, segment) {
return uri + segment + queryPortion;
};
+/** Builds a request object to GET the specified URI.
+ * @param {String} uri - URI for request.
+ * @param {Object} options - Additional options.
+ */
var buildODataRequest = function (uri, options) {
- /// <summary>Builds a request object to GET the specified URI.</summary>
- /// <param name="uri" type="String">URI for request.</param>
- /// <param name="options" type="Object">Additional options.</param>
-
+
return {
method: "GET",
requestUri: uri,
@@ -66,12 +73,12 @@ var buildODataRequest = function (uri, options) {
};
};
+/** Finds the index where the value of a query option starts.
+ * @param {String} uri - URI to search in.
+ * @param {String} name - Name to look for.
+ * @returns {Number} The index where the query option starts.
+ */
var findQueryOptionStart = function (uri, name) {
- /// <summary>Finds the index where the value of a query option starts.</summary>
- /// <param name="uri" type="String">URI to search in.</param>
- /// <param name="name" type="String">Name to look for.</param>
- /// <returns type="Number">The index where the query option starts.</returns>
-
var result = -1;
var queryIndex = uri.indexOf("?");
if (queryIndex !== -1) {
@@ -86,80 +93,81 @@ var findQueryOptionStart = function (uri, name) {
return result;
};
+/** Gets data from an OData service.
+ * @param {String} uri - URI to the OData service.
+ * @param {Object} options - Object with additional well-known request options.
+ * @param {Function} success - Success callback.
+ * @param {Function} error - Error callback.
+ * @returns {Object} Object with an abort method.
+ */
var queryForData = function (uri, options, success, error) {
- /// <summary>Gets data from an OData service.</summary>
- /// <param name="uri" type="String">URI to the OData service.</param>
- /// <param name="options" type="Object">Object with additional well-known request options.</param>
- /// <param name="success" type="Function">Success callback.</param>
- /// <param name="error" type="Function">Error callback.</param>
- /// <returns type="Object">Object with an abort method.</returns>
-
var request = queryForDataInternal(uri, options, {}, success, error);
return request;
};
- var queryForDataInternal = function (uri, options, data, success, error) {
- /// <summary>Gets data from an OData service taking into consideration server side paging.</summary>
- /// <param name="uri" type="String">URI to the OData service.</param>
- /// <param name="options" type="Object">Object with additional well-known request options.</param>
- /// <param name="data" type="Array">Array that stores the data provided by the OData service.</param>
- /// <param name="success" type="Function">Success callback.</param>
- /// <param name="error" type="Function">Error callback.</param>
- /// <returns type="Object">Object with an abort method.</returns>
-
- var request = buildODataRequest(uri, options);
- var currentRequest = odataRequest.request(request, function (newData) {
- var nextLink = newData["@odata.nextLink"];
- if (nextLink) {
- var index = uri.indexOf(".svc/", 0);
- if (index != -1) {
- nextLink = uri.substring(0, index + 5) + nextLink;
- }
+/** Gets data from an OData service taking into consideration server side paging.
+ * @param {String} uri - URI to the OData service.
+ * @param {Object} options - Object with additional well-known request options.
+ * @param {Array} data - Array that stores the data provided by the OData service.
+ * @param {Function} success - Success callback.
+ * @param {Function} error - Error callback.
+ * @returns {Object} Object with an abort method.
+ */
+var queryForDataInternal = function (uri, options, data, success, error) {
+
+ var request = buildODataRequest(uri, options);
+ var currentRequest = odataRequest.request(request, function (newData) {
+ var nextLink = newData["@odata.nextLink"];
+ if (nextLink) {
+ var index = uri.indexOf(".svc/", 0);
+ if (index != -1) {
+ nextLink = uri.substring(0, index + 5) + nextLink;
}
+ }
- if (data.value && newData.value) {
- data.value = data.value.concat(newData.value);
- }
- else {
- for (var property in newData) {
- if (property != "@odata.nextLink") {
- data[property] = newData[property];
- }
+ if (data.value && newData.value) {
+ data.value = data.value.concat(newData.value);
+ }
+ else {
+ for (var property in newData) {
+ if (property != "@odata.nextLink") {
+ data[property] = newData[property];
}
}
+ }
- if (nextLink) {
- currentRequest = queryForDataInternal(nextLink, options, data, success, error);
- }
- else {
- success(data);
- }
- }, error, undefined, options.httpClient, options.metadata);
+ if (nextLink) {
+ currentRequest = queryForDataInternal(nextLink, options, data, success, error);
+ }
+ else {
+ success(data);
+ }
+ }, error, undefined, options.httpClient, options.metadata);
- return {
- abort: function () {
- currentRequest.abort();
- }
- };
+ return {
+ abort: function () {
+ currentRequest.abort();
+ }
};
+};
+/** Creates a data cache source object for requesting data from an OData service.
+ * @param options - Options for the cache data source.
+ * @returns {ODataCacheSource} A new data cache source instance.
+ */
var ODataCacheSource = function (options) {
- /// <summary>Creates a data cache source object for requesting data from an OData service.</summary>
- /// <param name="options">Options for the cache data source.</param>
- /// <returns type="ODataCacheSource">A new data cache source instance.</returns>
-
var that = this;
var uri = options.source;
that.identifier = normalizeURICase(encodeURI(decodeURI(uri)));
that.options = options;
+ /** Gets the number of items in the collection.
+ * @param {Function} success - Success callback with the item count.
+ * @param {Function} error - Error callback.
+ * @returns {Object} Request object with an abort method.
+ */
that.count = function (success, error) {
- /// <summary>Gets the number of items in the collection.</summary>
- /// <param name="success" type="Function">Success callback with the item count.</param>
- /// <param name="error" type="Function">Error callback.</param>
- /// <returns type="Object">Request object with an abort method./<param>
-
var options = that.options;
return odataRequest.request(
buildODataRequest(appendSegment(uri, "$count"), options),
@@ -170,16 +178,18 @@ var ODataCacheSource = function (options) {
} else {
success(count);
}
- }, error, undefined, options.httpClient, options.metadata);
+ }, error, undefined, options.httpClient, options.metadata
+ );
};
-
+
+ /** Gets a number of consecutive items from the collection.
+ * @param {Number} index - Zero-based index of the items to retrieve.
+ * @param {Number} count - Number of items to retrieve.
+ * @param {Function} success - Success callback with the requested items.
+ * @param {Function} error - Error callback.
+ * @returns {Object} Request object with an abort method./<param>
+ */
that.read = function (index, count, success, error) {
- /// <summary>Gets a number of consecutive items from the collection.</summary>
- /// <param name="index" type="Number">Zero-based index of the items to retrieve.</param>
- /// <param name="count" type="Number">Number of items to retrieve.</param>
- /// <param name="success" type="Function">Success callback with the requested items.</param>
- /// <param name="error" type="Function">Error callback.</param>
- /// <returns type="Object">Request object with an abort method./<param>
var queryOptions = "$skip=" + index + "&$top=" + count;
return queryForData(appendQueryOption(uri, queryOptions), that.options, success, error);
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/datajs/deferred.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/datajs/deferred.js b/datajs/src/lib/datajs/deferred.js
index ab9bda3..513958d 100644
--- a/datajs/src/lib/datajs/deferred.js
+++ b/datajs/src/lib/datajs/deferred.js
@@ -16,45 +16,43 @@
* specific language governing permissions and limitations
* under the License.
*/
-
-var forwardCall = function (thisValue, name, returnValue) {
- /// <summary>Creates a new function to forward a call.</summary>
- /// <param name="thisValue" type="Object">Value to use as the 'this' object.</param>
- /// <param name="name" type="String">Name of function to forward to.</param>
- /// <param name="returnValue" type="Object">Return value for the forward call (helps keep identity when chaining calls).</param>
- /// <returns type="Function">A new function that will forward a call.</returns>
+/** Creates a new function to forward a call.
+ * @param {Object} thisValue - Value to use as the 'this' object.
+ * @param {String} name - Name of function to forward to.
+ * @param {Object} returnValue - Return value for the forward call (helps keep identity when chaining calls).
+ * @returns {Function} A new function that will forward a call.
+ */
+var forwardCall = function (thisValue, name, returnValue) {
return function () {
thisValue[name].apply(thisValue, arguments);
return returnValue;
};
};
+/** Initializes a new DjsDeferred object.
+ * Compability Note A - Ordering of callbacks through chained 'then' invocations
+ *
+ * The Wiki entry at http://wiki.commonjs.org/wiki/Promises/A
+ * implies that .then() returns a distinct object.
+ *
+ * For compatibility with http://api.jquery.com/category/deferred-object/
+ * we return this same object. This affects ordering, as
+ * the jQuery version will fire callbacks in registration
+ * order regardless of whether they occur on the result
+ * or the original object.
+ *
+ * Compability Note B - Fulfillment value
+ *
+ * The Wiki entry at http://wiki.commonjs.org/wiki/Promises/A
+ * implies that the result of a success callback is the
+ * fulfillment value of the object and is received by
+ * other success callbacks that are chained.
+ *
+ * For compatibility with http://api.jquery.com/category/deferred-object/
+ * we disregard this value instead.
+ */
var DjsDeferred = function () {
- /// <summary>Initializes a new DjsDeferred object.</summary>
- /// <remarks>
- /// Compability Note A - Ordering of callbacks through chained 'then' invocations
- ///
- /// The Wiki entry at http://wiki.commonjs.org/wiki/Promises/A
- /// implies that .then() returns a distinct object.
- ////
- /// For compatibility with http://api.jquery.com/category/deferred-object/
- /// we return this same object. This affects ordering, as
- /// the jQuery version will fire callbacks in registration
- /// order regardless of whether they occur on the result
- /// or the original object.
- ///
- /// Compability Note B - Fulfillment value
- ///
- /// The Wiki entry at http://wiki.commonjs.org/wiki/Promises/A
- /// implies that the result of a success callback is the
- /// fulfillment value of the object and is received by
- /// other success callbacks that are chained.
- ///
- /// For compatibility with http://api.jquery.com/category/deferred-object/
- /// we disregard this value instead.
- /// </remarks>
-
this._arguments = undefined;
this._done = undefined;
this._fail = undefined;
@@ -62,12 +60,15 @@ var DjsDeferred = function () {
this._rejected = false;
};
+
DjsDeferred.prototype = {
- then: function (fulfilledHandler, errorHandler /*, progressHandler */) {
- /// <summary>Adds success and error callbacks for this deferred object.</summary>
- /// <param name="fulfilledHandler" type="Function" mayBeNull="true" optional="true">Success callback.</param>
- /// <param name="errorHandler" type="Function" mayBeNull="true" optional="true">Error callback.</param>
- /// <remarks>See Compatibility Note A.</remarks>
+
+ /** Adds success and error callbacks for this deferred object.
+ * @param {function} [fulfilledHandler] - Success callback ( may be null)
+ * @param {function} [errorHandler] - Error callback ( may be null)
+ * See Compatibility Note A.
+ */
+ then: function (fulfilledHandler, errorHandler) {
if (fulfilledHandler) {
if (!this._done) {
@@ -100,11 +101,10 @@ DjsDeferred.prototype = {
return this;
},
+ /** Invokes success callbacks for this deferred object.
+ *All arguments are forwarded to success callbacks.
+ */
resolve: function (/* args */) {
- /// <summary>Invokes success callbacks for this deferred object.</summary>
- /// <remarks>All arguments are forwarded to success callbacks.</remarks>
-
-
if (this._done) {
var i, len;
for (i = 0, len = this._done.length; i < len; i++) {
@@ -126,9 +126,11 @@ DjsDeferred.prototype = {
}
},
+ /** Invokes error callbacks for this deferred object.
+ * All arguments are forwarded to error callbacks.
+ */
reject: function (/* args */) {
- /// <summary>Invokes error callbacks for this deferred object.</summary>
- /// <remarks>All arguments are forwarded to error callbacks.</remarks>
+
if (this._fail) {
var i, len;
for (i = 0, len = this._fail.length; i < len; i++) {
@@ -144,22 +146,21 @@ DjsDeferred.prototype = {
}
},
+ /** Returns a version of this object that has only the read-only methods available.
+ * @returns An object with only the promise object.
+ */
promise: function () {
- /// <summary>Returns a version of this object that has only the read-only methods available.</summary>
- /// <returns>An object with only the promise object.</returns>
-
var result = {};
result.then = forwardCall(this, "then", result);
return result;
}
};
+/** Creates a deferred object.
+ * @returns {DjsDeferred} A new deferred object. If jQuery is installed, then a jQueryDeferred object is returned, which provides a superset of features.
+*/
var createDeferred = function () {
- /// <summary>Creates a deferred object.</summary>
- /// <returns type="DjsDeferred">
- /// A new deferred object. If jQuery is installed, then a jQuery
- /// Deferred object is returned, which provides a superset of features.
- /// </returns>
+
if (window.jQuery && window.jQuery.Deferred) {
return new window.jQuery.Deferred();
http://git-wip-us.apache.org/repos/asf/olingo-odata4-js/blob/facdabac/datajs/src/lib/datajs/utils.js
----------------------------------------------------------------------
diff --git a/datajs/src/lib/datajs/utils.js b/datajs/src/lib/datajs/utils.js
index 605d5aa..6a98408 100644
--- a/datajs/src/lib/datajs/utils.js
+++ b/datajs/src/lib/datajs/utils.js
@@ -16,60 +16,59 @@
* specific language governing permissions and limitations
* under the License.
*/
-
+
+/** Creates a new ActiveXObject from the given progId.
+ * @param {String} progId - ProgId string of the desired ActiveXObject.
+ * @returns {Object} The ActiveXObject instance. Null if ActiveX is not supported by the browser.
+ * This function throws whatever exception might occur during the creation
+ * of the ActiveXObject.
+*/
var activeXObject = function (progId) {
- /// <summary>Creates a new ActiveXObject from the given progId.</summary>
- /// <param name="progId" type="String" mayBeNull="false" optional="false">
- /// ProgId string of the desired ActiveXObject.
- /// </param>
- /// <remarks>
- /// This function throws whatever exception might occur during the creation
- /// of the ActiveXObject.
- /// </remarks>
- /// <returns type="Object">
- /// The ActiveXObject instance. Null if ActiveX is not supported by the
- /// browser.
- /// </returns>
+
if (window.ActiveXObject) {
return new window.ActiveXObject(progId);
}
return null;
};
+/** Checks whether the specified value is different from null and undefined.
+ * @param [value] Value to check ( may be null)
+ * @returns {Boolean} true if the value is assigned; false otherwise.
+*/
var assigned = function (value) {
- /// <summary>Checks whether the specified value is different from null and undefined.</summary>
- /// <param name="value" mayBeNull="true" optional="true">Value to check.</param>
- /// <returns type="Boolean">true if the value is assigned; false otherwise.</returns>
return value !== null && value !== undefined;
};
+/** Checks whether the specified item is in the array.
+ * @param {Array} [arr] Array to check in.
+ * @param item - Item to look for.
+ * @returns {Boolean} true if the item is contained, false otherwise.
+*/
var contains = function (arr, item) {
- /// <summary>Checks whether the specified item is in the array.</summary>
- /// <param name="arr" type="Array" optional="false" mayBeNull="false">Array to check in.</param>
- /// <param name="item">Item to look for.</param>
- /// <returns type="Boolean">true if the item is contained, false otherwise.</returns>
-
var i, len;
for (i = 0, len = arr.length; i < len; i++) {
if (arr[i] === item) {
return true;
}
}
-
return false;
};
+/** Given two values, picks the first one that is not undefined.
+ * @param a - First value.
+ * @param b - Second value.
+ * @returns a if it's a defined value; else b.</returns>
+ */
var defined = function (a, b) {
- /// <summary>Given two values, picks the first one that is not undefined.</summary>
- /// <param name="a">First value.</param>
- /// <param name="b">Second value.</param>
- /// <returns>a if it's a defined value; else b.</returns>
+
return (a !== undefined) ? a : b;
};
+/** Delays the invocation of the specified function until execution unwinds.
+ * @param {Function} callback - Callback function.
+ */
var delay = function (callback) {
- /// <summary>Delays the invocation of the specified function until execution unwinds.</summary>
- /// <param name="callback" type="Function">Callback function.</param>
+
if (arguments.length === 1) {
window.setTimeout(callback, 0);
return;
@@ -81,12 +80,14 @@ var delay = function (callback) {
}, 0);
};
+/** Throws an exception in case that a condition evaluates to false.
+ * @param {Boolean} condition - Condition to evaluate.
+ * @param {String} message - Message explaining the assertion.
+ * @param {Object} data - Additional data to be included in the exception.
+ */
// DATAJS INTERNAL START
var djsassert = function (condition, message, data) {
- /// <summary>Throws an exception in case that a condition evaluates to false.</summary>
- /// <param name="condition" type="Boolean">Condition to evaluate.</param>
- /// <param name="message" type="String">Message explaining the assertion.</param>
- /// <param name="data" type="Object">Additional data to be included in the exception.</param>
+
if (!condition) {
throw { message: "Assert fired: " + message, data: data };
@@ -94,12 +95,12 @@ var djsassert = function (condition, message, data) {
};
// DATAJS INTERNAL END
+/** Extends the target with the specified values.
+ * @param {Object} target - Object to add properties to.
+ * @param {Object} values - Object with properties to add into target.
+ * @returns {Object} The target object.
+*/
var extend = function (target, values) {
- /// <summary>Extends the target with the specified values.</summary>
- /// <param name="target" type="Object">Object to add properties to.</param>
- /// <param name="values" type="Object">Object with properties to add into target.</param>
- /// <returns type="Object">The target object.</returns>
-
for (var name in values) {
target[name] = values[name];
}
@@ -108,10 +109,11 @@ var extend = function (target, values) {
};
var find = function (arr, callback) {
- /// <summary>Returns the first item in the array that makes the callback function true.</summary>
- /// <param name="arr" type="Array" optional="false" mayBeNull="true">Array to check in.</param>
- /// <param name="callback" type="Function">Callback function to invoke once per item in the array.</param>
- /// <returns>The first item that makes the callback return true; null otherwise or if the array is null.</returns>
+ /** Returns the first item in the array that makes the callback function true.
+ * @param {Array} [arr] Array to check in. ( may be null)
+ * @param {Function} callback - Callback function to invoke once per item in the array.
+ * @returns The first item that makes the callback return true; null otherwise or if the array is null.
+ */
if (arr) {
var i, len;
@@ -125,66 +127,65 @@ var find = function (arr, callback) {
};
var isArray = function (value) {
- /// <summary>Checks whether the specified value is an array object.</summary>
- /// <param name="value">Value to check.</param>
- /// <returns type="Boolean">true if the value is an array object; false otherwise.</returns>
+ /** Checks whether the specified value is an array object.
+ * @param value - Value to check.
+ * @returns {Boolean} true if the value is an array object; false otherwise.
+ */
return Object.prototype.toString.call(value) === "[object Array]";
};
+/** Checks whether the specified value is a Date object.
+ * @param value - Value to check.
+ * @returns {Boolean} true if the value is a Date object; false otherwise.
+ */
var isDate = function (value) {
- /// <summary>Checks whether the specified value is a Date object.</summary>
- /// <param name="value">Value to check.</param>
- /// <returns type="Boolean">true if the value is a Date object; false otherwise.</returns>
-
return Object.prototype.toString.call(value) === "[object Date]";
};
+/** Tests whether a value is an object.
+ * @param value - Value to test.
+ * @returns {Boolean} True is the value is an object; false otherwise.
+ * Per javascript rules, null and array values are objects and will cause this function to return true.
+ */
var isObject = function (value) {
- /// <summary>Tests whether a value is an object.</summary>
- /// <param name="value">Value to test.</param>
- /// <remarks>
- /// Per javascript rules, null and array values are objects and will cause this function to return true.
- /// </remarks>
- /// <returns type="Boolean">True is the value is an object; false otherwise.</returns>
return typeof value === "object";
};
+/** Parses a value in base 10.
+ * @param {String} value - String value to parse.
+ * @returns {Number} The parsed value, NaN if not a valid value.
+*/
var parseInt10 = function (value) {
- /// <summary>Parses a value in base 10.</summary>
- /// <param name="value" type="String">String value to parse.</param>
- /// <returns type="Number">The parsed value, NaN if not a valid value.</returns>
-
return parseInt(value, 10);
};
+/** Renames a property in an object.
+ * @param {Object} obj - Object in which the property will be renamed.
+ * @param {String} oldName - Name of the property that will be renamed.
+ * @param {String} newName - New name of the property.
+ * This function will not do anything if the object doesn't own a property with the specified old name.
+ */
var renameProperty = function (obj, oldName, newName) {
- /// <summary>Renames a property in an object.</summary>
- /// <param name="obj" type="Object">Object in which the property will be renamed.</param>
- /// <param name="oldName" type="String">Name of the property that will be renamed.</param>
- /// <param name="newName" type="String">New name of the property.</param>
- /// <remarks>
- /// This function will not do anything if the object doesn't own a property with the specified old name.
- /// </remarks>
-
if (obj.hasOwnProperty(oldName)) {
obj[newName] = obj[oldName];
delete obj[oldName];
}
};
+/** Default error handler.
+ * @param {Object} error - Error to handle.
+ */
var throwErrorCallback = function (error) {
- /// <summary>Default error handler.</summary>
- /// <param name="error" type="Object">Error to handle.</param>
throw error;
};
+/** Removes leading and trailing whitespaces from a string.
+ * @param {String str String to trim
+ * @returns {String} The string with no leading or trailing whitespace.
+ */
var trimString = function (str) {
- /// <summary>Removes leading and trailing whitespaces from a string.</summary>
- /// <param name="str" type="String" optional="false" mayBeNull="false">String to trim</param>
- /// <returns type="String">The string with no leading or trailing whitespace.</returns>
-
if (str.trim) {
return str.trim();
}
@@ -192,15 +193,14 @@ var trimString = function (str) {
return str.replace(/^\s+|\s+$/g, '');
};
+/** Returns a default value in place of undefined.
+ * @param [value] Value to check (may be null)
+ * @param defaultValue - Value to return if value is undefined.
+ * @returns value if it's defined; defaultValue otherwise.
+ * This should only be used for cases where falsy values are valid;
+ * otherwise the pattern should be 'x = (value) ? value : defaultValue;'.
+ */
var undefinedDefault = function (value, defaultValue) {
- /// <summary>Returns a default value in place of undefined.</summary>
- /// <param name="value" mayBeNull="true" optional="true">Value to check.</param>
- /// <param name="defaultValue">Value to return if value is undefined.</param>
- /// <returns>value if it's defined; defaultValue otherwise.</returns>
- /// <remarks>
- /// This should only be used for cases where falsy values are valid;
- /// otherwise the pattern should be 'x = (value) ? value : defaultValue;'.
- /// </remarks>
return (value !== undefined) ? value : defaultValue;
};
@@ -214,13 +214,11 @@ var undefinedDefault = function (value, defaultValue) {
var uriRegEx = /^([^:\/?#]+:)?(\/\/[^\/?#]*)?([^?#:]+)?(\?[^#]*)?(#.*)?/;
var uriPartNames = ["scheme", "authority", "path", "query", "fragment"];
+/** Gets information about the components of the specified URI.
+ * @param {String} uri - URI to get information from.
+ * @return {Object} An object with an isAbsolute flag and part names (scheme, authority, etc.) if available.
+ */
var getURIInfo = function (uri) {
- /// <summary>Gets information about the components of the specified URI.</summary>
- /// <param name="uri" type="String">URI to get information from.</param>
- /// <returns type="Object">
- /// An object with an isAbsolute flag and part names (scheme, authority, etc.) if available.
- /// </returns>
-
var result = { isAbsolute: false };
if (uri) {
@@ -241,11 +239,11 @@ var getURIInfo = function (uri) {
return result;
};
+/** Builds a URI string from its components.
+ * @param {Object} uriInfo - An object with uri parts (scheme, authority, etc.).
+ * @returns {String} URI string.
+ */
var getURIFromInfo = function (uriInfo) {
- /// <summary>Builds a URI string from its components.</summary>
- /// <param name="uriInfo" type="Object"> An object with uri parts (scheme, authority, etc.).</param>
- /// <returns type="String">URI string.</returns>
-
return "".concat(
uriInfo.scheme || "",
uriInfo.authority || "",
@@ -264,11 +262,11 @@ var uriAuthorityRegEx = /^\/{0,2}(?:([^@]*)@)?([^:]+)(?::{1}(\d+))?/;
// Regular expression that matches percentage enconded octects (i.e %20 or %3A);
var pctEncodingRegEx = /%[0-9A-F]{2}/ig;
+/** Normalizes the casing of a URI.
+ * @param {String} uri - URI to normalize, absolute or relative.
+ * @returns {String} The URI normalized to lower case.
+*/
var normalizeURICase = function (uri) {
- /// <summary>Normalizes the casing of a URI.</summary>
- /// <param name="uri" type="String">URI to normalize, absolute or relative.</param>
- /// <returns type="String">The URI normalized to lower case.</returns>
-
var uriInfo = getURIInfo(uri);
var scheme = uriInfo.scheme;
var authority = uriInfo.authority;
@@ -293,12 +291,12 @@ var normalizeURICase = function (uri) {
});
};
+/** Normalizes a possibly relative URI with a base URI.
+ * @param {String} uri - URI to normalize, absolute or relative
+ * @param {String} base - Base URI to compose with (may be null)
+ * @returns {String} The composed URI if relative; the original one if absolute.
+ */
var normalizeURI = function (uri, base) {
- /// <summary>Normalizes a possibly relative URI with a base URI.</summary>
- /// <param name="uri" type="String">URI to normalize, absolute or relative.</param>
- /// <param name="base" type="String" mayBeNull="true">Base URI to compose with.</param>
- /// <returns type="String">The composed URI if relative; the original one if absolute.</returns>
-
if (!base) {
return uri;
}
@@ -339,12 +337,12 @@ var normalizeURI = function (uri, base) {
return getURIFromInfo(normInfo);
};
+/** Merges the path of a relative URI and a base URI.
+ * @param {String} uriPath - Relative URI path.</param>
+ * @param {String} basePath - Base URI path.
+ * @returns {String} A string with the merged path.
+ */
var mergeUriPathWithBase = function (uriPath, basePath) {
- /// <summary>Merges the path of a relative URI and a base URI.</summary>
- /// <param name="uriPath" type="String>Relative URI path.</param>
- /// <param name="basePath" type="String">Base URI path.</param>
- /// <returns type="String">A string with the merged path.</returns>
-
var path = "/";
var end;
@@ -360,11 +358,11 @@ var mergeUriPathWithBase = function (uriPath, basePath) {
return path + uriPath;
};
+/** Removes the special folders . and .. from a URI's path.
+ * @param {string} path - URI path component.
+ * @returns {String} Path without any . and .. folders.
+ */
var removeDotsFromPath = function (path) {
- /// <summary>Removes the special folders . and .. from a URI's path.</summary>
- /// <param name="path" type="string">URI path component.</param>
- /// <returns type="String">Path without any . and .. folders.</returns>
-
var result = "";
var segment = "";
var end;