RecipeRPC Reference Implementation 0.4

This page describes how to install and use the RecipeRPC Reference Implementation version 0.4. For more information on RecipeRPC, see the RecipeRPC home page.

Server installation

The server requires PHP 4 and an appropriate webserver (such as Apache) to run. MySQL is required if you want to store your recipes in a database (you will want to do this if you have more than about 1000 recipes). Ensure you have these items installed before beginning.

To install the server, first download the installation package recipe_rpc_server-0.4.zip. Next, unzip the file using an unzip utility. For example, on Unix type

unzip recipe_rpc_server-0.4.zip

Ensure you unzip to a location visible to your webserver. For instance, with Apache webservers, you pick a home directory in httpd.conf and the webserver can only see files inside this directory.

You now have a directory called recipe_rpc_server-0.4 containing these items:

admin directory. Contains administration code and the admin.php page for changing parameters.
impl directory. Contains back-end logic for storing and fetching recipes. Two types are available: file-based storage and MySQL storage.
xml directory. Repository for RecipeML recipes to be provided by the server. 100 recipes supplied with the package; feel free to add or replace with your own.
xmlrpc directory. Contains XML-RPC for PHP, the library used by the server for XML-RPC plumbing.
public.inc. Contains functions that report server statistics, like number of recipes stored.
public.php. Example of a web page displaying server statistics.
reciperpc.php. The server PHP file. Point clients to this file.
saverecipe.php. Prompts the user to save a recipe. Used to work around sandboxing restrictions (see implementation notes below).
usage.html. This documentation page.
util.inc. Various utility functions.

After unzipping, ensure your webserver is running. Then check that your webserver can see the directory by pointing a browser to this page, usage.html. For instance, if your server is located at www.myserver.com and you unzipped directly into the home directory of your Apache server, then point a browser to http://www.myserver.com/recipe_rpc_server-0.4/usage.html. If you don't see this page, check your webserver configuration to figure out what is wrong (usually access permissions).

If this works, you are ready to point a client at the server. Follow the instructions in the next section to install and run the RecipeRPC Reference Implementation Client; if you are using a different client, give it the domain of your webserver and the URI for reciperpc.php.

Client installation

To install the client, first download the installation package reciperpcclient-0.4.zip. Next, unzip the file using an unzip utility. For example, on Unix type

unzip reciperpcclient-0.4.zip

You now have a number of files in a directory called recipe_rpc_client-0.4. The files are:

minml.jar. The MinML
reciperpcapplet-0.4.jar. Code that displays the applet in your browser.
reciperpcclient-0.4.jar. Code that handles communication with the RecipeRPC server.
xmlrpc.jar. The Marquee XML-RPC library.
usage.html. This documentation page.

To use the applet on a web page, put all the jar files listed above in the same location as your web page, then include this tag in the HTML at the location where you would like the applet:

<APPLET CODE="com/reciperpc/Applet/RecipeRPCApplet.class" 
        ARCHIVE="reciperpcapplet-0.4.jar,reciperpcclient-0.4.jar,xmlrpc.jar,minml.jar" 
        DOMAIN="SERVER DOMAIN"
        PORT="SERVER PORT NUMBER"
        SERVERDIR="SERVER DIRECTORY"
        XMLRPCFILE="reciperpc.php"
        XMLFILE="saverecipe.php"
        LOG="false"
        TIME="false"
        SAVEBUTTON="true"
        WIDTH=550 
        HEIGHT=500/>

Replace the parameter values in capital letters with the corresponding items for your server. For instance, for the RecipeRPC sample server, the domain is reciperpc.sf.net, the port is 80 (this is the standard port for HTTP traffic), and the server directory is /RPC2/. You can also set the LOG parameter if you want logging, perhaps to help you debug your installation; to accomodate the larger log window, you probably also should set WIDTH and HEIGHT to 600 each. The TIME parameter, if set to true, causes the applet to time each server request and report it in the status window. The SAVEBUTTON parameter enables or disables the Save XML button.

Remember that an untrusted applet can only open an HTTP connection to the host that provided it. Thus, for example, you can't point your applet to the RecipeRPC sample server. Of course, you are free to create a trusted applet, or a non-applet client, that isn't bound by this security restriction.

Now that the applet is installed, you can open your web page. You should see a message in the window at the bottom confirming successful connection; if not, set LOG="true" to chase down the error. Once you see the confirming message, usage is simple: enter a name and click Search, then pick a recipe and click Open to see the recipe. Use Previous and Next to get more recipes, if your initial search didn't bring back all the available recipes. You can save the XML for the currently displayed recipe with the Save XML button.

Customising and monitoring the server

You will likely want to adjust various parameters on the server. To do this, point a browser to the admin/admin.php page. This page provides forms that let you do the following:

Switch between file storage (the default) and database storage.
Set the directory where RecipeML files are stored (if you are using file storage).
Set parameters that tell the server where the MySQL server is and how to connect to it (if you are using database storage).
Change the log file name, or disable server logging.
Change the number of recipes returned by each search() call.
Enable or disable truncation on the dbadmin.php page (see below).

You probably want to ensure that only you or another authorised person can access the admin.php page, as well as the other files in the admin directory - since anyone with access to these files could cause accidental or intentional damage to your server and its data. Use your webserver's security features to do this - for instance, on Apache you can use various forms of authentication.

You can review a summary of the data in your server log file - if you are using one - in the admin/stats.php file. By default, the page reports on activity during the last seven days; you can adjust this using the form at the bottom of the page.

You can administer your database - if you are using a MySQL database - with the dbadmin.php page. The page provides forms with which you upload recipe files from a specified directory or delete all recipes - the latter is only enabled if you set a parameter on the main admin.php page, to keep you from deleting all your recipes accidentally. If you need to do more sophisticated database management - deleting specific recipes or tuning the table for better query performance, for instance - consider using a tool like PHPMyAdmin.

The server makes some simple statistics available for inclusion in web pages - for instance, your home page can include the statement "15,357 recipes now available!". Your web page will need to use PHP to include() the public.inc file, then call one or more of the functions made available in that file. See public.php for a simple web page that displays all the available statistics.

Implementation and the RecipeRPC spec

There are several ways that this early reference implementation differs from the RecipeRPC specification. This section describes each of these items, as well as some other implementation specifics.

No server selection. An ideal client would permit you to select from a range of servers, and to search one or many of them. However, an untrusted applet can only talk to its own host, so the client doesn't offer the user any choice of server. Server selection would be easy to implement with a different front-end, such as a trusted applet or standalone application.

No authentication. In the interest of simplicity, the server ignores usernames and passwords. Because the server ignores them, the applet doesn't ask for the username and password. The client package reciperpcclient-0.4.jar, however, will pass through usernames and passwords to the server, if you write a front-end that supplies them - you would want to do this if you want to use the client to talk to servers that require authentication. A future version will include usernames and passwords, but the deployed version on the RecipeRPC site won't require them.

Limited format support. The server only supplies recipes in RecipeML format. This is just to keep this example implementation simple; modifying the server to supply recipes in several formats would not be difficult. Accordingly, the applet doesn't have a format field, and the client does not attempt to interpret any format other than RecipeML.

Limited searching. The server only supports simple searches for substrings of the recipe name. A future version will allow searches on category, yield, and other items.

Save XML button. The client fetches the recipe, but can't save it to the local drive because it is an untrusted applet. The applet and server therefore have to do a little dance when you click the Save XML button:

The applet tells the browser to open the web page specified by the XMLFile parameter. The page includes a GET parameter giving the recipe ID.
The web page, written in PHP, uses the ID to fetch the recipe and returns it to the browser.
Headers in the HTTP response tell the browser to save the file (most browsers will prompt the user to select a location and confirm the download).

An implementation with a non-sandboxed front-end would, of course, just save the recipe directly, without the need for this extra round-trip.

Logging. The server logs requests to a file, stamped with the user's IP address and the time of the request. You adjust the logfile name, or turn off logging altogether, using the administration page.