net.myrrix.web
Class Runner

java.lang.Object
  net.myrrix.web.Runner

All Implemented Interfaces:

Closeable, Callable<Boolean>

public final class Runner
extends Object
implements Callable<Boolean>, Closeable

This is the runnable class which starts the Serving Layer and its Tomcat-based HTTP server. It is started with call() and can be shut down with close(). This implementation is used both in stand-alone local mode, and in a distributed mode cooperating with a Computation Layer.

This program instantiates a Tomcat-based HTTP server exposing a REST-style API. It is available via HTTP, or HTTPS as well if RunnerConfiguration.getKeystoreFile() is set. It can also be password protected by setting RunnerConfiguration.getUserName() and RunnerConfiguration.getPassword().

Runner is configured by RunnerConfiguration but when run as a command-line program, it is configured via a set of analogous flags:

• --localInputDir: Optional. The local directory used for reading input, writing output, and storing user input and model files in local mode. It is used for staging input for upload in distributed mode. Defaults to the system temp directory.
• --bucket: Identifies the root directory of storage under which data is stored and computation takes place in distributed mode. Only applicable in distributed mode. Must be set with --instanceID.
• --instanceID: Uniquely identifies the recommender from others that may be run by the same organization. Only applicable in distributed mode. Must be set with --bucket.
• --port: Port on which to listen for HTTP requests. Defaults to 80. Note that the server must be run as the root user to access port 80.
• --securePort: Port on which to listen for HTTPS requests. Defaults to 443. Likewise note that using port 443 requires running as root.
• --keystoreFile: File containing the SSL key to use for HTTPS. Note that setting this flag enables HTTPS connections, and so requires that options keystorePassword be set.
• --keystorePassword: Password for keystoreFile.
• --userName: If specified, the user name required to authenticate to the server using HTTP DIGEST authentication. Requires password to be set.
• --password: Password for HTTP DIGEST authentication. Requires userName to be set.
• --consoleOnlyPassword: Only apply username and password to admin / console pages.
• --rescorerProviderClass: Optional. Name of an implementation of RescorerProvider to use to rescore recommendations and similarities, if any. The class must be added to the server classpath.
• --allPartitions: Optional, but must be set with --partition. Describes all partitions, when partitioning across Serving Layers by user. Each partition may have multiple replicas. Serving Layers are specified as "host:port". Replicas are specified as many Serving Layers, separated by commas, like "rep1:port1,rep2:port2,...". Finally, partitions are specified as multiple replicas separated by semicolon, like "part1rep1:port11,part1rep2:port12;part2rep1:port21,part2rep2:port22;...". Example: "foo:80,foo2:8080;bar:8080;baz2:80,baz3:80"
• --partition: Optional, but must be set with --allPartitions. The partition (0-based) that this is Serving Layer is serving.

When run in local mode, the Serving Layer instance will compute a model locally and save it as the file model.bin in the --localInputDir directory. It will be updated when the model is rebuilt. If the file is present at startup, it will be read to restore the server state, rather than re-reading CSV input in the directory and recomputing the model. Thus the file can be saved and restored as a way of preserving and recalling the server's state of learning.

Example of running in local mode:

java -jar myrrix-serving-x.y.jar --port=8080

(with an example of JVM tuning flags:)

java -jar myrrix-serving-x.y.jar -server -da -dsa -d64 -Xmx1g -XX:NewRatio=12 -XX:+UseParallelGC -XX:+UseParallelOldGC --port=8080

Finally, some more advanced tuning parameters are available. These are system parameters, set with -Dproperty=value.

• model.features: The number of features used in building the underlying user-feature and item-feature matrices. Typical values are 30-100. Defaults to MatrixFactorizer#DEFAULT_FEATURES.
• model.iterations: The number of iterations used to refine the model. Typical values are 3-10. Defaults to MatrixFactorizer#DEFAULT_ITERATIONS.
• model.als.lambda: Controls the lambda overfitting parameter in the ALS algorithm. Typical values are near 0.1. Do not change this, in general. Defaults to AlternatingLeastSquares#DEFAULT_LAMBDA.
• model.als.alpha: Controls the alpha scaling parameter in the ALS algorithm. Typical values are near 40. Do not change this, in general. Defaults to AlternatingLeastSquares#DEFAULT_ALPHA.

Author:

Sean Owen

Constructor Summary

Runner(RunnerConfiguration config)
Creates a new instance with the given configuration.

Method Summary

void	await() Blocks and waits until the server shuts down.
Boolean	call()
void	close()
org.apache.catalina.startup.Tomcat	getTomcat()
static void	main(String[] args)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Runner

public Runner(RunnerConfiguration config)

Creates a new instance with the given configuration.

Method Detail

getTomcat

public org.apache.catalina.startup.Tomcat getTomcat()

Returns:

the underlying Tomcat server that is being configured and run inside this instance.

main

public static void main(String[] args)
                 throws Exception

Throws:

Exception

call

public Boolean call()
             throws IOException

Specified by:

call in interface Callable<Boolean>

Throws:

IOException

await

public void await()

Blocks and waits until the server shuts down.

close

public void close()

Specified by:

close in interface Closeable