Traveling Salesman Example: Persistent Data in MATLAB Production Server

This example shows how to effectively synchronize multi-client access to
a single shared data structure. It consists of two parts: A MATLAB App and
a set of MATLAB functions deployed to a MATLAB Production Server instance.
The MATLAB app provides a simple UI to help a traveling salesman determine
the best route to visit a set of customer locations. The archive of deployed
functions finds minimal distance routes and manages the persistent data: 
a collection of customer locations and the distances between them.

This document describes how to build and run the example. You will need
MATLAB, MATLAB Compiler SDK and MATLAB Production Server. At several points
these instructions refer to MATLAB Production Server commands such as
'mps-new'. If you are unsure how to use these commands, consult the 
documentation. You may instead use the MATLAB Production Server Dashboard to
manage MATLAB Production server instances, though these instructions do not
provide the necessary steps. Note: to use the commands, you must have the 
MATLAB Production Server scripts directory on your system path. 

You may also run Traveling Salesman in MATLAB, without using MATLAB 
Production Server, though you will still need Compiler SDK for the 
persistence service. See "Running Traveling Salesman in MATLAB," below.

#### Running Traveling Salesman using MATLAB Production Server ####

Overview of the process:
1. Copy the example files to a writeable folder.
2. Create the deployable archive.
3. Deploy the archive to a MATLAB Production Server instance.
   If necessary, install MATLAB Production Server first.
4. Start the MATLAB Production Server instance and a Redis persistence
   service.
5. Run the Traveling Salesman MATLAB app.

1: First, copy the all the files in the example directory to a writeable 
folder, for example /Work/TravelingSalesman. Start MATLAB and set the 
current working directory to that folder using the CD command.

2.1: Build the deployable archive. Start productionServerCompiler:

>> cd /Work/TravelingSalesman
>> productionServerCompiler

2.2: Click "+" in the top toolstrip to add these three functions from the 
TravelingSalesman example directory to the list of exported functions:
   findRoute.m
   addDestination.m  
   listDestinations.m

2.3: In the "Archive information" section, change the archive name to:
'TravelingSalesman' (without the quotes). 

2.4: Click "+" in the "Additional Files required for your archive 
to run" section to add the file Distances.xlsx (located in the
TravelingSalesman example directory).

2.5: Click the big green checkmark in the "Package" section of the top 
toolstrip to create the deployable archive TravelingSalesman.ctf.

3. Install and configure a MATLAB Production Server instance with the 
mps-new command. For example: 

C:\> mps-new /Work/TravelingSalesman/example_mps

4.1: The deployable archive requires a persistence service connection named 
'ScratchPad'. Use the MATLAB Production Server Dashboard to create
the 'ScratchPad' connection or copy the file mps_cache_config from this
example directory to the config directory of your MATLAB Production Server
instance. If you already have an mps_cache_config in your config directory,
edit it to add the 'ScratchPad' connection shown in the example
mps_cache_config.

4.2: Copy the deployable archive TravelingSalesman.ctf created in step 2 to 
the auto_deploy directory of the MATLAB Production Server instance you set
up in step 3.

4.3: Start the MATLAB Production Server instance with the mps-start command.
For example: 

C:\> mps-start -C /Work/TravelingSalesman/example_mps

4.4: The 'ScratchPad' connection is configured for a Redis persistence
server. Start a Redis server using the mps-cache command. For example:

C:\> mps-cache start -C /Work/TravelingSalesman --connection ScratchPad

5. Start the TravelingSalesman app in MATLAB:

>> cd /Work/TravelingSalesman
>> TravelingSalesman

#### Running Traveling Salesman in MATLAB ####

By default, the Traveling Salesman app uses local functions to compute the
shortest path. It uses functions deployed to MATLAB Production Server when 
host and port are set to the network address of a MATLAB Production Server
instance.

Before starting Traveling Salesman, you must connect to a persistence service.
The app expects the connection to be named 'ScratchPad'. Use mps.cache.control
to create the ScratchPad connection to the MatlabTest persistence service,
which uses MAT-files to store persistent data.


>> cd /Work/TravelingSalesman
>> ctrl = mps.cache.control('ScratchPad', 'MatlabTest');
>> start(ctrl)
>> TravelingSalesman
>> ...
>> stop(ctrl)

#### Troubleshooting ####

==== 404 Component Not Found ====

If you see this error:

Error using readContentFromWebService (line 46)
The server returned the status 404 with message "ComponentNotFound
Component not found. (request id=0:0:0)" in response to the request
to URL http://localhost:9910/TravelingSalesman/listDestinations.

MATLAB Production Server can't find the archive TravelingSalesman.ctf in the 
auto_deploy folder. Mostly likely causes: 

* The archive has the wrong name -- capitalization matters.
* The archive isn't there at all.

See step 2.3 for instructions on naming the archive when you package it.
Repackage the archive and copy it to the auto_deploy directory.

==== Unable to open Distances.xlsx ====

If you see this error:

Error using TravelingSalesman/listDestinationsProxy (line 150)
Unable to open file 'Distances.xlsx' as a workbook. Check that the
file exists, read access is available, and the file is a valid
spreadsheet file.

You probably forgot to add Distances.xlsx to the archive. See step 2.4. 
Once you have added Distances.xlsx, repackage the archive and copy it to
the auto_deploy directory.

==== Connection Refused ====

If you see this error:

Error using webwrite (line 136)
The error "Connection refused" occurred while communicating with URL
'http://localhost:9910/TravelingSalesman/listDestinations'.

It is likely that the MATLAB Production Server instance is not running. The
server instance may also be running on an unexpected host and port. The
MATLAB app expects to find MATLAB Production Server on localhost:9910, the
default host and port.

If you can, modify your server instance to run on localhost:9910. If that's
not possible, you can edit TravelingSalesman.mlapp to change the host and
port it expects. Run the MATLAB command 'appdesigner TravelingSalesman.mlapp',
find the app.HostEditField and app.PortEditField in the Component Browser 
and set their values to the host and port used by your server instance.


