text: /*
   * Copyright 2013 Jive Software
   *
   *    Licensed under the Apache License, Version 2.0 (the "License");
   *    you may not use this file except in compliance with the License.
   *    You may obtain a copy of the License at
   *
   *       http://www.apache.org/licenses/LICENSE-2.0
   *
   *    Unless required by applicable law or agreed to in writing, software
   *    distributed under the License is distributed on an "AS IS" BASIS,
   *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   *    See the License for the specific language governing permissions and
   *    limitations under the License.
   */
  
  /**
   * EXAMPLE: Demonstates how to kick off service autowiring a directory of tiles.
   */
  
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Setup express
  
  var express = require('express'),
      jive = require('jive-sdk');
  
  var app = express();
  
  
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Setup jive
  
  var failServer = function(reason) {
      console.log('FATAL -', reason );
      process.exit(-1);
  };
  
  var startServer = function () {
      if ( !jive.service.role || jive.service.role.isHttp() ) {
          var server = app.listen( app.get('port') || 8090, app.get('hostname') || undefined, function () {
              console.log("Express server listening on " + server.address().address +':'+server.address().port);
          });
      }
  };
  
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Setting up your service
  
  //
  // Service startup sequence (Easy as 1-2-3!):
  //
  
  // 1. initialize service setup -- optionally pass in a JSON configuration object or path to a configuration object;
  // if one is not provided, it assumes that [app root]/jiveclientconfiguration.json file exists.
  jive.service.init(app)
  
  // 2. autowire all available definitions in /tiles; see explanation below.
  .then( function() { return jive.service.autowire() } )
  
  // 3. start the service, which performs sanity checks such as clientId, clientSecret, and clientUrl defined.
  // if successful service start, call the start the http server function defined by you; otherwise call the
  // fail one
  .then( function() { return jive.service.start() } ).then( startServer, failServer );
  
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Below is an explanation of each step in the above sequence successful.
  
  /*
  ====================
  Step 1. Service Init
  ====================
  
  jive.service.init() must at minimum be called with an app, as the framework will use that to
  prepare the express app.
  
  A second argument (omitted above) can be provided, which can be either (1) the JSON for the options
  required to start the service (clientUrl, port), or the location of a JSON
  file containing those setup options.
  
  If no 2nd argument is provided, then the system will try to locate a command line parameter to
  node called config (eg. configFile=/path/to/my.json), or an environment variable (eg. CONFIG_FILE=/path/to/my.json).
  
  If neither are present, the system will assume that a file [app root]/jiveclientconfiguration.json] exists, and
  will try to parse that file for options.
  
  ==================
  Step 2. Autowiring
  ==================
  
  Once jive.service.init() completes, the next promise in the chain above is jive.service.autowire(), which
  will inspect your system for tiles and external stream definitions in [app root]/tiles, and automatically try to
  discover definition JSON, routes, tasks, and event handlers that are placed there in expected locations.
  
  The .autowire() assumes the following directory structure exists:
  [app root]/tiles
              /tile1
                  /public (optional)
                      configuration.html (optional)
                  /backend (optional)
                      *.js
                      /routes (optional)
                          /config (optional)
                              get.js (optional)
                  definition.json (optional)
  
  Note: The optional items above are recommended.
  
  Regarding the /routes directory:
  --------------------------------
  The system will recursively search for .js files exporting either a function(req, res), or
  a routes datastructure, and construct a route based on the path in the directory, for the
  associated tile. You should refer to these routes in your definition.json (eg. the "configure"
  and "register" attributes for example), so that a Jive instance receiving the definition for your
  tile or external activity stream will know which endpoints to call for producing the configuration UI
  for your tile, and for which endpoints to call when registering a tile or activity stream instance.
  
  Route autowiring can happen with two possible flavors:
  
  (1) Route autowire by verb file (get.js, put.js, delete.js, post.js)
  
  If a .js file in the routes directory corresponds to one of the http verbs (eg. get.js, put.js, delete.js, post.js),
  and the exported function is named 'route' specifically, a node JS express route will be created
  based on the directory path. For example:
  
              ..
              /samplelist
                  /backend
                      /routes
                          /config
                              get.js
  
  Assuming that /samplelist/backend/routes/config/get.js contains the following:
  
              exports.route = function(req, res) { ..  };
  
  The following route will be automatically created:
  
              GET /samplelist/config
  
  You may then safely reference this route in your definition.json:
  
              {
               ..
                   "config": "/samplelist/configure",
               ..
              }
  
  (2) Route autowire by datastructure
  If the .js file exports a datastructure containing BOTH "verb" string and "route" function attributes,
  the system will attempt to construct a node JS express route based on the directory path plus either
  name of the exported datastructure (or an optional "path" parameter", and
  set the verb to the value of the verb attribute.
  
  For example:
  
              exports.mypath = {
                  'verb': 'get',
                  'route': function(res,req) { .. }
              };
  
  Assuming that this export lives in /samplelist/routes/prod/extra/routes.js, the following route will be automatically
  created:
  
              GET /samplelist/prod/extra/mypath
  
  If a path attribte was present:
  
           exports.mypath = {
               'path' : 'more',
               'verb': 'get',
               'route': function(res,req) { .. }
           };
  
  The following path will be autowired:
  
          GET /samplelist/prod/extra/mypath/more
  
  As with the autowire by verb file example above, you should reference these routes in your definition.json.
  
  Regarding the backend directory:
  --------------------------------
  Though the system will search for .js files anywhere under the tile directory, it is good practice to put your
  services related items in a specific backend directory.
  
  The system will try to discover any event handlers and tasks exported in .js files.
  
  (1) Event Handlers
  If you have a file that exports an .eventHandlers array property, the system will call jive.definitions.addEventHandler()
  on each of the object elements.
  For example:
  
  If in /samplelist/services/lifecycle.js this existed:
  
          exports.eventHandlers = [
           { 'event': 'destroyingInstance',
             'handler' : function(theInstance){
                   override
               }
           }
          ];
  
  This will add the event listener 'destroyingInstance' to the definition samplelist, which will be called
  whenever an instance of samplelist is destroyed.
  
  (2) Task exports
  If you have a file that exports a .task property, the system will call jive.definitions.addTasks( .. ) on that
  object, which can be either a task object (see jive-sdk/lib/task.js) or a function.
  
  If in /samplelist/backend/datapusher.js this existed:
  
       exports.task = function() { .. }
               - or -
       exports.task = jive.tasks.build( function() { ..} , 5000 )
  
  This will schedule a task based on the function in either statement to execute either every 15 seconds
  (default for a plain function), or the interval specified in the task (5 seconds in the provided example).
  
  Regarding definition.json:
  -------------------------
  If a definition.json file is located in a tile directory (for example /samplelist/definition.json), the system
  will call either jive.tile.definitions or jive.extstreams.definitions .save(), based on the "style" attribute
  in this json structure. If style is "ACTIVITY", jive.extstreams.definitions.save() will be called; otherwise
  its assumed to be a tile, and jive.tiles.definitions.save() will be called.
  
  When the /tiles development endpoints are called, it will return all the tiles and external stream definitions
  defined in your system through the aforementioned .save() command. The tile definitions output via this
  endpoint is in the format expected by the jivelinks API.
  
  (1) If the "configure" attribute is not specified, the value will be interpreted as
       [clientUrl]/[tile name]/configure. Please make sure this endpoint
       is available either through manual configuration, or route autowiring (see above).
  (2) If "registration" attribute is not specified, the value will be interpreted as
       http[your service url]/registration (this is the shared, framework provided registration endpoint).
  (3) Any paths containing  will have that value substituted with the value of clientUrl from your
      configuration file.
  
  =====================
  Step 3. START SERVICE
  =====================
   The final link in the promise chain is jive.service.start(), which performs the following:
   - Prepares the express app based passed in the first step, .init() above, adding globally available
     endpoints such as:
          /registration
          /tiles (dev mode only)
  
  - Validates service setup options, making sure that require attributes such as
  clientUrl are present
  - If there are any problems, the failure callback on the .then() of this promise gets executed, and the
    service process exits with an error. Otherwise the http server starts when the success callback is executed.
  
  At this point, the service should be ready to serve purposeful places integrations.
  
  In development mode, you can inspect what tiles are active on the service by invoking:
  
      GET /tiles
  
  */
  