LassoProxy API

Lasso 3 has built-in support for serving information from FileMaker Pro databases to Java applets. This means the applet creator can utilize the power of Lasso and FileMaker Pro to create sophisticated solutions which are not confined by the limitations of HTML. Applets can utilize multiple databases simultaneously and can present the information in ways not possible with HTML. Applet programmers can take advantage of this new feature by utilizing the LassoProxy classes. The LassoProxy classes are a set of Java source files which can be compiled with Java applets. The classes know how to formulate Lasso requests, send them to the server where Lasso is running, and make the results available for the applet to use. By using this API, applets can perform any of the database activities possible with HTML forms. They can perform finds, updates, deletes and can create new records in the FileMaker Pro databases.

The LassoProxy classes communicate with Lasso using standard HTTP. They formulate a request string based on the parameters the applet programmer selects, then the classes send the request to the server. Lasso then returns the response but instead of returning it as HTML, as it would normally, it sends only the data and lets the applet choose how to display it. Applets can elect to only receive certain fields from the database, making the response very compact and efficient.

(Note: The Java_Client_Enabler module is required to enable client-side Java communication.)

There are three Java classes programmers can use to communicate with Lasso:

1. LassoRequest
2. LassoProxy
3. LassoResponse

The first class, LassoRequest, is used to set up the action Lasso will take. Using just a few of the classes' methods, the programmer can specify the database, layout and fields used for the request.

The following Java snippets show how to set up a request to perform a search:

1. Create a new Lasso Request object.

      LassoRequest request = new LassoRequest();

2. Assign the database name and layout name to be used in the search.

      request.setDatabaseName("MyDatabase");    
      request.setLayoutName("MyLayout");

3. Specify the action to be taken.

      request.setAction(LassoRequest.SEARCH);

4. Add the fields to be searched and the values to be searched for along with the search operators to be used for each field.

      request.addField("Field_One", "searchvalue", LassoRequest.EQUALS);
      request.addField("Field_Two", "another value", LassoRequest.BEGINS_WITH);

The search request is now completely set up and is ready to be processed. Additional options are available to the programmer such as setting the maximum number of records to be returned, setting the logical operator (AND or OR) on a global or field level, specifying a timeout or sort criteria. All of these operations can be performed with ease using only a few additional lines of code.

When a request is ready to be processed, the second class, LassoProxy is required. The LassoProxy class takes a LassoRequest object, sends the request data to the server where Lasso is running, and receives the response from the server. The LassoProxy object then converts the response data into a LassoReponse object which the programmer can use to retrieve the search results. All of this processing happens behind the scenes. The programmer only needs to use one of the LassoProxy class' methods to process the entire request.

To process the request object created earlier, the following steps are required:

1. Create a LassoProxy object. The LassoProxy object requires an URL object to be created. The getDocumentBase() method returns an URL object representing the server the applet was downloaded and run from.

   LassoProxy proxy = new LassoProxy(getDocumentbase());

2. Have the LassoProxy object process the request. It will return a LassoResponse object. Here, the LassoProxy object is passed the LassoRequest object (called "request"). Within the Lasso request object is the search request created earlier.

   LassoResponse response = proxy.processRequest(request);

Now that the request has been sent to Lasso and the results have been returned, the programmer can use the LassoResponse class to retrieve this information. The information which the programmer has access to includes:

1. A result code indicating if the request was successfully processed

2. The number of records returned

3. The total number of records in the database

4. The names, types and value lists (if any) for each of the fields on the specified layout and the data

5. Record ids for the returned records. All of this information can be retrieved using the various methods belonging to the response object. Below are some examples of how the data can be retrieved.

All examples assume a LassoResponse object called "response" was created earlier.

1. Retrieve the names of all the fields in the previously specified database. The names are returned as an array of strings. Standard Java code can be used to further process this array as required. This snippet will print the number of fields and their names to the standard output.

String names = response.fieldNames();
    System.out.println("There are " + names.length + 
        " fields in the database:");
for (int i = 0; i < names.length; ++i) System.out.println("\t" + names[i]);

2. Retrieve the types of data the fields can hold. Each field in the database is defined to hold a particular type of data. Some hold text, some hold dates or times and some can hold pictures. The following snippet prints the type of each field to the standard output.

for (int i = 0; i < response.numFields(); ++i)
{
    System.out.print("Field " + response.fieldNames()[i] + " is a ");
    switch(response.fieldType(i))
    {
        case LassoResponse.CHAR:
            System.out.println("CHAR");
            break;
        case LassoResponse.SHORT_INTEGER:
            System.out.println("SHORT_INTEGER");
            break;
        case LassoResponse.INTEGER:
            System.out.println("INTEGER");
            break;
        case LassoResponse.SHORT_FLOAT:
            System.out.println("SHORT_FLOAT");
            break;
        case LassoResponse.FLOAT:
            System.out.println("FLOAT");
            break;
        case LassoResponse.IMAGE:
            System.out.println("IMAGE");
            break;
        case LassoResponse.DATE_TIME:
            System.out.println("DATE_TIME");
            break;
        case LassoResponse.BOOLEAN:
            System.out.println("BOOLEAN");
            break;
        default:
            System.out.println("strange type");
            break;
    }
}

3. Retrieve the data from the returned records. The following snippet will print the data in each field for each of the returned records to the standard output.

System.out.println("Here is the returned data:");
    // loop for each record
    for (int recordNum = 0; recordNum < response.numRecords(); ++recordNum)
    {
        System.out.println("\tRecord number " + recordNum + ":");
        // loop for each field
        for (int fieldNum = 0; fieldNum < response.numFields(); ++fieldNum)
        {
            System.out.println("\t\tField name: " + response.fieldNames()[fieldNum]);
            // loop for each value the field may contain
            for (int valueNum = 0; valueNum < response.fieldData(recordNum, fieldNum).length, ++valueNum)
            {
                System.out.println("\t\t\t"
                    + response.fieldValue(recordNum, fieldNum, valueNum));
            }
        }
    }

4. More Examples

More examples can be found distributed with Lasso. These examples show how to retrieve information about databases and how to search, add, update and delete records using the LassoProxy API.