Docs: Java Client

Java API

The Java Client may be called directly from Java code, via ClientRecommender. This implements MyrrixRecommender and has all of the same methods available from other recommender implementations. For example, to recommend 5 items to user 123:

List<RecommendedItem> recommendations = clientRecommender.recommend(123, 5);

The ClientRecommender makes HTTP requests to a remote instance of the Serving Layer over HTTP. It must therefore be configured for use by creating and setting values
of MyrrixClientConfiguration. For example:

MyrrixClientConfiguration clientConfig = new MyrrixClientConfiguration();
clientConfig.setHost("example.org");
// These lines only needed if you enabled HTTPS
clientConfig.setPort(443);
clientConfig.setSecure(true);
// These lines only needed if you set a username and password
clientConfig.setUserName("foo"); 
clientConfig.setPassword("bar");
ClientRecommender clientRecommender = new ClientRecommender(clientConfig);

When configured to do so, it can operate with distributed Serving Layer instances and will automatically direct a request to the right partition and replica.

Note that it is also possible to obfuscate user and item IDs at the client side for security. To do this, the client translates from real ID values to hashed numeric values and vice versa, entirely on the client side. As a side effect this also allows for the use of String identifiers for users and items.

To use this, create a TranslatingClientRecommender. This is a wrapper class attached to a configured instance of ClientRecommender. It adds analogous methods that take
String instead of long identifiers. For example:

List<TranslatedRecommendedItem> recommendations = clientRecommender.recommend("Jane", 5);

Command Line

The client provides a basic command-line interface to the Java client. It is run like so:

java -jar myrrix-client-X.Y.jar [options] command [arg0 arg1 ...]

options may include:

command corresponds to methods of MyrrixRecommender. The remaining arguments are arguments to the method named by command, and are likewise analogous to the method arguments seen in MyrrixRecommender. The complete set of commands and arguments are:

• setPreference userID itemID [value]
• removePreference userID itemID
• ingest csvFile.csv(.gz|.zip) [csvFile2 ...]
• estimatePreference userID itemID1 [itemID2 ...]
• recommend userID
• recommendToAnonymous itemID1 [itemID2 ...]
• mostSimilarItems itemID1 [itemID2 ...]
• similarityToItem toItemID itemID1 [itemID2 ...]
• recommendedBecause userID itemID
• refresh
• isReady
• getAllUserIDs
• getAllItemIDs
• getNumUserClusters
• getNumItemClusters
• getUserCluster n
• getItemCluster n

Note: since some arguments like IDs can be negative, and begin with "-", they are mistakenly interpreted as flags by the command line parser. Double-quote such values. Note further than in command-line shells like bash, the double-quote is parsed by the shell, and so must be escaped. To specify the value -100 for example, write \"-100\".

Methods whose counterparts return void produce no output. Methods like estimatePreference that return a single value have this written to a single line of output. Methods like recommend that return a series of values are output in CSV format.

For example, to make 3 recommendations for user 35, one might run:

java -jar myrrix-client-X.Y.jar --host example.com --howMany 3 recommend 35

... and output might be:

352352,0.559
9898,0.4034
209,0.03339

If using string IDs, it might look more like:

java -jar myrrix-client-X.Y.jar --host example.com --translate ids.txt --howMany 3 recommend Jane

... and output might be:

Apple,0.559
Orange,0.4034
Banana,0.03339

Finally, the client's behavior can be controlled more exactly with optional system properties. Use normal Java syntax to specify these: java -Dkey=value ...

curl

Common command-line tools like curl can also be used, since the REST API is accessed with simply a series of HTTP requests. Some examples follow; modify the URL (host, port, HTTP/S) to match that of the Serving Layer.

• curl -F file=@/your/data.csv http://host/ingest uploads a file of CSV data
• curl http://host/recommend/user prints recommendations for a user to the console
• curl -X POST http://host/refresh triggers a model rebuild / reload
• curl -d "value" http://host/pref/user/item adds a user-item association, with given value
• curl -X DELETE http://host/pref/user/item removes a user-item association

Adding To Your Project

All classes needed to use the Java Client are contained in myrrix-client-x.y.jar. Simply add this JAR file to your classpath or project.

If your project's build uses Apache Maven, simply depend on artifact myrrix-client from group ID net.myrrix:

<dependency>
  <groupId>net.myrrix</groupId>
  <artifactId>myrrix-client</artifactId>
  <version>x.y</version>
</dependency>

Javadoc

Browse the Java Client Javadoc.