Key Information

Register
Submit
The challenge is finished.

Challenge Overview

Hercules PCDVR HTML App - JavaScript Services Assembly Specification

Overview

The Hercules PCDVR project allows users to upload their media to the Hercules cloud servers, including photos, videos, and music, along with other files.  The client already has working iOS and Android apps that work with the client services.  This architecture is kicking off the HTML5 application that allows users to do the same thing they can with the mobile apps.  This architecture will define the JavaScript classes and calls to interface with the client's backend services.

This assembly will implement the entire JavaScript services module.

Data Models

The data models used in this assembly are presented on "JavaScript Services Class Diagram".

Note that the data models are just mappings to JSON resource objects defined in the client's REST API or used to encapsulate API call request options, there is NO need to explicitly define JavaScript "classes" for them, but please document the JSON object structure in relevant service documentation.

For example, File data model represents a file in the client's REST API, and it maps to JSON object as follows:

{
  "fileguid": "daea0d30-294d-11e4-9ee9-fa163ec722ac",
  "albumguid": "9e8541a0-26ca-11e4-bfcf-fa163e89ec2a",
  "name": "Test File",
  "deleted": false,
  "thumbnailUrl": "/thumbnails/daea0d30-294d-11e4-9ee9-fa163ec722ac",
  "mediaUrl": "http://ugc-media-qa.comcast.net/media/media/daeb6cc0-294d-11e4-9ee9-fa163ec722ac?authtoken=gyLt4JmJ8GO0Neeyi7hR4_kSNJ9TnTn4mw0LQzaBSMkC7Ga3zvKSKT6drvGo7XxiGoyK0-2NROJLmGd_IZZ3MaDHrcEfAsZr3l0tMT0Q7pE",
  "mediaStatus": "UPLOAD-COMPLETE",
  "size": 10567,
  "type": "PNG",
  "mimeType": "image/png",
  "duration": "",
  "otherFormat": "",
  "avgBitRate": "",
  "imageSize": "1024x1024",
  "rotation": "",
  "genre": "",
  "title": "",
  "artist": "",
  "eTag": "864cf2db6f8412583531e2f0beb9c538",
  "isNew": false,
  "lastModifiedDate": "2014-08-21T16:11:37.798",
  "createdDate": "2014-08-21T16:11:37.798"
}

JavaScript Services

A set of JavaScript services will be implemented in this application, which provides UI JavaScript the access to various business operations.

Specifically the following services will be implemented, please refer to "JavaScript Services Class Diagram" for more information and implementation details.

  • BaseService

This is the base service that provides an abstract sendRequest method to access remote API server.

  • AlbumService

This service provides methods to manage albums.

  • FileService

This service provides methods to manage files.

  • MediaService

This service provides methods to manage file media data.

  • ActivityService

This service provides methods to access user activities.

  • ThumbnailService

This service provides a method to get full thumbnail URL.

The following principles will be followed in the JavaScript service implementation:

  • The JavaScript services will be defined in a namespace "com.hercules.ugc.services" so that the global namespace won't be polluted.
  • Some services inherit from BaseService using JavaScript prototype.
  • Separate JS files will be used for each service.
  • com.hercules.ugc.services.Globals is used to hold common configurations and provides methods to set/get access token. Access token will be stored in HTML5 sessionStorage so that it can survive page refresh but not window/tab close.
  • The functions of services are implemented in asynchronous manner, i.e. all functions will take a callback function that will be called to notify function caller of result. The callback function generally receives an error message (if operation failed) or the operation result (if operation succeeded). Note that not all operations require operation result, so some callbacks will only accept the error message parameter. 

The following code snippet illustrates the implementation patterns of the JavaScript services:

/* Globals.js defines the namespace and Globals */
// define namespace
var com = com || {};
com.hercules = {};
com.hercules.ugc = {};
com.hercules.ugc.services = {};
com.hercules.ugc.services.Globals = {
    REST_API_BASE_URL : 'https://secure.api.comcast.net/xcloud-qa',
    setAccessToken : ...,
    getAccessToken : ...
};

/* BaseService.js defines the BaseService */
// Utility to implement prototype inheritance
if (typeof Object.create !== 'function') {
    Object.create = function (o) {
        function F() {}
        F.prototype = o;
        return new F();
    };
}
// BaseService
com.hercules.ugc.services.BaseService = {};
com.hercules.ugc.services.BaseService.sendRequest = ...;

/* AlbumService.js defines the AlbumService */
com.hercules.ugc.services.AlbumService = Object.create(com.hercules.ugc.services.BaseService);
com.hercules.ugc.services.AlbumService.getMyAlbums = ...;
...

/* FileService.js defines the FileService */
com.hercules.ugc.services.FileService = Object.create(com.hercules.ugc.services.BaseService);
com.hercules.ugc.services.FileService.getMyFiles = ...;
...

/* MediaService.js defines the MediaService */
com.hercules.ugc.services.MediaService = Object.create(com.hercules.ugc.services.BaseService);
com.hercules.ugc.services.MediaService.uploadMedia = ...;
...

/* ActivityService.js defines the ActivityService */
com.hercules.ugc.services.ActivityService = Object.create(com.hercules.ugc.services.BaseService);
com.hercules.ugc.services.ActivityService.getMyActivities = ...;
...

/* ThumbnailService.js defines the ThumbnailService*/
com.hercules.ugc.services.ThumbnailService = {};
com.hercules.ugc.services.ThumbnailService.getFullThumbnailUrl = ...;

Configuration

The only configuration used in JavaScript services is the base URL of the client's REST API, which is specified in com.hercules.ugc.services.Globals.REST_API_BASE_URL. The URL should not include trailing "/" character.

In production environment, the URL will be https://secure.api.comcast.net/xcloud

In QA environment, the URL will be https://secure.api.comcast.net/xcloud-qa

JavaScript services caller may override this configuration simply by changing its value, e.g.

com.hercules.ugc.services.Globals.REST_API_BASE_URL = 'https://secure.api.comcast.net/xcloud';

Logging

loglevel library will be used to perform logging.

Errors will be logged at ERROR level, debug information (like method entry/exit, input parameters, etc.) will be logged at DEBUG level. API requests/responses should be logged at DEBUG level, and the access token must NOT be included in the log message. For instance:

log.error('Error occurred ' + error);
log.debug('Entering FileService.getMyFiles...');

In production environment, only ERROR level logging should be enabled, all other logging levels should be disabled as follows:

log.setLevel('error');

Exception Handling

The functions of JavaScript services are implemented in asynchronous manner, i.e. most functions will take a callback function that will be called to notify function caller of result. If error occurs, callback function will be called with a string detailing the error.

HTTP response status codes are used in the client's API server to indicate errors, and the JavaScript services will interpret status codes other than 200 as errors accordingly (this behavior is provided by the XHR wrapper library).

Many JavaScript service methods will validate input parameters and use callback to report invalid inputs (if the callback function itself is not provided, the error message will be thrown to the caller directly). For service methods without callback function (i.e. the synchronous method calls), an error message will be thrown to the caller directly.

Test Pages

In addition to the Javascript libraries, you must provide some basic test pages that allow reviewers to:

  • Login
  • Upload an image or video
  • Perform all operations, including "GET" calls
  • Validate the JSON output for each call 

Please use a small Bootstrap.css template so that the test pages look good and are usuable for future work, and for demo'ing to the client.

Browser Support

The following browsers must be supported:

  • IE 10+
  • Chrome 4+
  • Firefox 3.5+
  • Safari 4+

Deliverables

  • Source code and configuration files.
  • Deployment guide to configure and verify the application.
  • Test page showing uploading working for a given image

Technology overview

Existing Documents

  • Class Diagram
  • Sequence Diagrams
  • Application Design Specification
  • Assembly Specification


Final Submission Guidelines

Please see above

ELIGIBLE EVENTS:

2015 topcoder Open

REVIEW STYLE:

Final Review:

Community Review Board

Approval:

User Sign-Off

SHARE:

ID: 30045540