PtolemyServer

java.lang.Object
- ptserver.control.PtolemyServer

All Implemented Interfaces:

IServerManager
```
public final class PtolemyServer
extends java.lang.Object
implements IServerManager
```
The PtolemyServer class is responsible for fulfilling simulation requests. To do this, the server hosts a servlet through the Jetty servlet container that enables clients to administer control commands for starting, pausing, resuming, and stopping simulations. The server also launches a separate process for the MQTT broker which is used for transmitting tokens between the client and server.
PtolemyServer uses mosquitto from http://mosquitto.org/download.

Under Windows, there is a mosquitto binary available for download.

Under Mac OS X:
1. Install cmake from http://www.cmake.org/cmake/resources/software.html or from http://mxcl.github.com/homebrew
2. Download and untar the mosquitto sources:
```
 cd $PTII/vendors
 wget http://mosquitto.org/files/source/mosquitto-0.10.2.tar.gz
 tar -zxf mosquitto-0.10.2.tar.gz
 cd mosquitto-0.10.2
 
```
3. Run:
```
 cmake .
 make
 sudo make install
 
```
This class requires that the mosquitto binary be running. Under Mac OS X:
```
 /usr/local/sbin/mosquitto &
 
```
See the tests in $PTII/ptserver/test/junit for simple code that uses this class.
Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Justin Killian

Pt.AcceptedRating:

Red (jkillian)

Pt.ProposedRating:

Red (jkillian)

Field Summary

Fields
Modifier and Type	Field and Description
`static java.util.ResourceBundle`	`CONFIG` The ResourceBundle containing configuration parameters.
`static int`	`IMAGE_BUFFER_SIZE` Buffer size to be used when exporting the model image.
`static java.lang.String`	`IMAGE_FORMAT` Export format of the model image.
`static java.util.logging.Logger`	`LOGGER` The logger that will record Ptolemy errors to the log file.
`static java.lang.String`	`SERVLET_NAME` The virtual path of the command servlet.
`static java.lang.String`	`SERVLET_ROLE` Roles to classify users during basic authentication.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close(Ticket ticket)` Shut down the simulation thread by calling the finish() method on its Manager and removing the task from the server.
`static void`	`createInstance(int servletPort, java.lang.String brokerPath, java.lang.String brokerAddress, int brokerPort, java.lang.String modelDirectory)` Create the singleton with non-default configuration values.
`byte[]`	`downloadModel(java.lang.String url)` Download the selected model to the client.
`java.lang.String`	`getBrokerUrl()` Get the full URL to the message broker.
`static PtolemyServer`	`getInstance()` Get the singleton instance of the Ptolemy server.
`java.lang.String[]`	`getLayoutListing(java.lang.String url)` Get a listing of the layouts for a specific model available on the server in either the database or the local file system.
`java.lang.String[]`	`getModelListing()` Get a listing of the models available on the server in either the database or the local file system.
`java.lang.String`	`getServletUrl()` Get the full URL to the servlet application.
`SimulationTask`	`getSimulationTask(Ticket ticket)` Get the simulation task of the provided ticket.
`Manager.State`	`getStateOfSimulation(Ticket ticket)` Get the current state of a specific simulation based on the simulation manager's state.
`java.util.LinkedHashMap<java.lang.String,java.lang.String>`	`getTokenHandlerMap()` Get the token handlers loaded on the server so that they can be set up on the client.
`static void`	`main(java.lang.String[] args)` Initialize the Ptolemy server, set up the servlet host, and wait for simulation requests.
`int`	`numberOfSimulations()` Get the number of simulation on the server.
`ProxyModelResponse`	`open(java.lang.String modelUrl, java.lang.String layoutUrl)` Open a model with the provided model URL and wait for the user to request the execution of the simulation.
`void`	`pause(Ticket ticket)` Pause the execution of the simulation by calling the pause() method on its Manager.
`void`	`resume(Ticket ticket)` Resume the execution of the simulation by calling the resume() method on its Manager.
`void`	`shutdown()` Shut down the broker process and stop all active simulation threads by calling their Managers.
`void`	`start(Ticket ticket)` Start the execution of the simulation by utilizing a free thread within the pool.
`void`	`stop(Ticket ticket)` Stop the execution of the simulation by calling the finish() method on its Manager.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CONFIG
```
public static final java.util.ResourceBundle CONFIG
```
    The ResourceBundle containing configuration parameters.
  - LOGGER
```
public static final java.util.logging.Logger LOGGER
```
    The logger that will record Ptolemy errors to the log file.
  - IMAGE_FORMAT
```
public static final java.lang.String IMAGE_FORMAT
```
    Export format of the model image.
    
    See Also:
    
    Constant Field Values
  - IMAGE_BUFFER_SIZE
```
public static final int IMAGE_BUFFER_SIZE
```
    Buffer size to be used when exporting the model image.
    
    See Also:
    
    Constant Field Values
  - SERVLET_NAME
```
public static final java.lang.String SERVLET_NAME
```
    The virtual path of the command servlet.
    
    See Also:
    
    Constant Field Values
  - SERVLET_ROLE
```
public static final java.lang.String SERVLET_ROLE
```
    Roles to classify users during basic authentication.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - close
```
public void close(Ticket ticket)
           throws IllegalActionException
```
    Shut down the simulation thread by calling the finish() method on its Manager and removing the task from the server.
    
    Specified by:
    
    close in interface IServerManager
    
    Parameters:
    
    ticket - Ticket reference to the simulation request.
    
    Throws:
    
    IllegalActionException - If the server was unable to destroy the simulation thread.
  - createInstance
```
public static void createInstance(int servletPort,
                                  java.lang.String brokerPath,
                                  java.lang.String brokerAddress,
                                  int brokerPort,
                                  java.lang.String modelDirectory)
                           throws IllegalActionException
```
    Create the singleton with non-default configuration values.
    If any of the parameters are null, then values in the ptserver.PtolemyServerConfig resource are checked. Typically, this file may be found as $PTII/ptserver/PtolemyServerConfig.properties.
    
    Parameters:
    
    servletPort - The port on which the servlet operates.
    
    brokerPath - The path to the broker executable.
    
    brokerAddress - The host address of the MQTT broker.
    
    brokerPort - The port of the broker.
    
    modelDirectory - The root directory of where model files are stored. If the value of the modelDirectory is not a directory, then a directory relative to the value of the ptolemy.ptII.dir (aka $PTII) property is checked. If that directory does not exist, then $PTII/ptserver/demo is used.
    
    Throws:
    
    IllegalActionException - If the server could not be created.
  - downloadModel
```
public byte[] downloadModel(java.lang.String url)
                     throws IllegalActionException
```
    Download the selected model to the client.
    
    Specified by:
    
    downloadModel in interface IServerManager
    
    Parameters:
    
    url - URL of the model file.
    
    Returns:
    
    Byte array containing the model data.
    
    Throws:
    
    IllegalActionException - If the server encountered an error opening the model file.
  - getBrokerUrl
```
public java.lang.String getBrokerUrl()
```
    Get the full URL to the message broker.
    
    Returns:
    
    The URL to the servlet including port.
  - getInstance
```
public static PtolemyServer getInstance()
                                 throws IllegalActionException
```
    Get the singleton instance of the Ptolemy server. If it does not already exist, the singleton will be instantiated using the default configuration.
    
    Returns:
    
    The PtolemyServer singleton.
    
    Throws:
    
    IllegalActionException - If the server could not be launched.
  - getLayoutListing
```
public java.lang.String[] getLayoutListing(java.lang.String url)
                                    throws IllegalActionException
```
    Get a listing of the layouts for a specific model available on the server in either the database or the local file system.
    
    Specified by:
    
    getLayoutListing in interface IServerManager
    
    Parameters:
    
    url - Address of the model file for which layouts are found.
    
    Returns:
    
    An array of URLs for the layouts available for the model on the server.
    
    Throws:
    
    IllegalActionException - If there was a problem discovering available layouts.
  - getModelListing
```
public java.lang.String[] getModelListing()
                                   throws IllegalActionException
```
    Get a listing of the models available on the server in either the database or the local file system.
    
    Specified by:
    
    getModelListing in interface IServerManager
    
    Returns:
    
    An array of URLs for the models available on the server.
    
    Throws:
    
    IllegalActionException - If there was a problem discovering available models.
  - getServletUrl
```
public java.lang.String getServletUrl()
```
    Get the full URL to the servlet application.
    
    Returns:
    
    The URL to the servlet including port.
  - getSimulationTask
```
public SimulationTask getSimulationTask(Ticket ticket)
                                 throws IllegalActionException
```
    Get the simulation task of the provided ticket.
    
    Parameters:
    
    ticket - The ticket associated with the simulation task.
    
    Returns:
    
    the simulation task associated with the provided ticket.
    
    Throws:
    
    IllegalActionException - if the ticket is invalid.
  - getStateOfSimulation
```
public Manager.State getStateOfSimulation(Ticket ticket)
                                   throws IllegalActionException
```
    Get the current state of a specific simulation based on the simulation manager's state.
    
    Parameters:
    
    ticket - The ticket reference to the simulation request.
    
    Returns:
    
    The state of the queried simulation.
    
    Throws:
    
    IllegalActionException - If the ticket is invalid or the state of the running situation could not be determined.
  - getTokenHandlerMap
```
public java.util.LinkedHashMap<java.lang.String,java.lang.String> getTokenHandlerMap()
                                                                              throws IllegalActionException
```
    Get the token handlers loaded on the server so that they can be set up on the client.
    
    Specified by:
    
    getTokenHandlerMap in interface IServerManager
    
    Returns:
    
    The token handler map from the server.
    
    Throws:
    
    IllegalActionException - If the server was unable to get the handler map.
  - main
```
public static void main(java.lang.String[] args)
                 throws IllegalActionException
```
    Initialize the Ptolemy server, set up the servlet host, and wait for simulation requests.
    This class requires that the mosquitto binary be running. See the class comment for information about building, installing and invoking mosquitto.
    
    The following optional command line switches may be used with their accompanying value: -servlet_port, -broker_path (if launching local broker), -broker_address, -broker_port, and -model_dir. The port numbers must be integers, the broker path must be the path to the MQTT broker executable, and the broker address must be the host address. The default values for the command line switches is read from the values in the ptserver.PtolemyServerConfig resource. Typically, this file may be found as $PTII/ptserver/PtolemyServerConfig.properties.
    
    For example:
```
  java -classpath java -classpath $PTII:${PTII}/ptserver/lib/hessian-4.0.7.jar:${PTII}/ptserver/lib/jetty-all-7.4.1.v20110513.jar:${PTII}/ptserver/lib/servlet-api-2.5.jar:${PTII}/ptserver/lib/wmqtt.jar \
      ptserver.control.PtolemyServer \
      -broker_address 192.168.125.169 -broker_port 1883
  
```
    Parameters:
    
    args - Optional command line arguments.
    
    Throws:
    
    IllegalActionException - If the server could not be launched.
  - numberOfSimulations
```
public int numberOfSimulations()
```
    Get the number of simulation on the server. The current thread pool implementation allows for an infinite number of concurrent simulations rather than limiting the server to finite amount.
    
    Returns:
    
    The number of active simulations as well as the queued requests that have not yet been fulfilled.
  - open
```
public ProxyModelResponse open(java.lang.String modelUrl,
                               java.lang.String layoutUrl)
                        throws IllegalActionException
```
    Open a model with the provided model URL and wait for the user to request the execution of the simulation.
    
    Specified by:
    
    open in interface IServerManager
    
    Parameters:
    
    modelUrl - The path to the model file
    
    layoutUrl - The path to a model's layout file
    
    Returns:
    
    The user's reference to the simulation task
    
    Throws:
    
    IllegalActionException - If the model fails to load from the provided URL.
  - pause
```
public void pause(Ticket ticket)
           throws IllegalActionException
```
    Pause the execution of the simulation by calling the pause() method on its Manager.
    
    Specified by:
    
    pause in interface IServerManager
    
    Parameters:
    
    ticket - The ticket reference to the simulation request.
    
    Throws:
    
    IllegalActionException - If the server was unable to pause the running simulation.
  - resume
```
public void resume(Ticket ticket)
            throws IllegalActionException
```
    Resume the execution of the simulation by calling the resume() method on its Manager.
    
    Specified by:
    
    resume in interface IServerManager
    
    Parameters:
    
    ticket - The ticket reference to the simulation request.
    
    Throws:
    
    IllegalActionException - If the server was unable to resume the execution of the simulation.
  - shutdown
```
public void shutdown()
              throws IllegalActionException
```
    Shut down the broker process and stop all active simulation threads by calling their Managers.
    
    Throws:
    
    IllegalActionException - If the servlet, broker, or thread pool cannot be stopped.
  - start
```
public void start(Ticket ticket)
           throws IllegalActionException
```
    Start the execution of the simulation by utilizing a free thread within the pool.
    
    Specified by:
    
    start in interface IServerManager
    
    Parameters:
    
    ticket - The ticket reference to the simulation request.
    
    Throws:
    
    IllegalActionException - If the server was unable to start the simulation.
  - stop
```
public void stop(Ticket ticket)
          throws IllegalActionException
```
    Stop the execution of the simulation by calling the finish() method on its Manager.
    
    Specified by:
    
    stop in interface IServerManager
    
    Parameters:
    
    ticket - The ticket reference to the simulation request.
    
    Throws:
    
    IllegalActionException - If the server was unable to stop the simulation.

Class PtolemyServer

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CONFIG

LOGGER

IMAGE_FORMAT

IMAGE_BUFFER_SIZE

SERVLET_NAME

SERVLET_ROLE

Method Detail

close

createInstance

downloadModel

getBrokerUrl

getInstance

getLayoutListing

getModelListing

getServletUrl

getSimulationTask

getStateOfSimulation

getTokenHandlerMap

main

numberOfSimulations

open

pause

resume

shutdown

start

stop