/* -*-Java-*-

********************************************************************************

*

* File:         CollectionPlug.java

* RCS:          $Header: /u/testbed/CVSROOT/dldev/doc/Visigenic/InfoBus/StreetRouterProxy/CollectionPlug.Street,v 1.1 1998/05/19 23:23:30 paepcke Exp $

* Description:  Mediates Between InfoBus Protocol Engine and Service Interface

* Author:       Gerard Rodriguez, Stanford University

* Created:      Wed Jan 15 10:10:21 1998

* Modified:     Thu Apr 16 13:13:19 1998 (Andreas Paepcke) paepcke@SNUGGLES

* Language:     Java

* Package:      N/A

* Status:       Experimental (Do Not Distribute)

*

* (c) Copyright 1998, Stanford University, all rights reserved.

*

********************************************************************************

*

* Revisions:

*

* Wed Apr 15 10:11:17 1998 (Andreas Paepcke) paepcke@SNUGGLES

*  Rewrote to match our new, cleaned-up specification.

********************************************************************************

*/



/**

CollectionPlug mediates between the DLIOP protocol engine

(DLIOPwrapper.java), and StreetRouterServer, which knows how to

interact with the street router program MapQuest via the Web.  The

methods in this class are called by the DLIOPwrapper. The collection

plug establishes a connection with MapQuest, submits queries,

stores the results, and returns them to DLIOPWrapper as requested.

<p>

Note that this street routing example is somewhat degenerate, because

the result of each search (i.e. each request for a route) always

returns a single result, namely the string with the driving directions.

So some of the features, such as sequential access to subsequent

documents in a result set that normally would be used in a collection

plug are not really exercised in this example. However, we have 

included the corresponding code anyway (loops that only run for one

iteration, etc.), so this should still work well as an example.

<p>

Further documentation: About DLIOP, see 

   http://www-diglib.stanford.edu/cgi-bin/WP/get/SIDL-WP-1997-0054

For an explanation of what collection plugs do, see: ****

*/



import java.io.*;

import java.awt.*;

import java.net.*;

import java.lang.*;



public class CollectionPlug {



  private String TheQuery;

  private String content;

  private int numDocs;  // number of docs found as result of a search

  private int theDocCursor; // next new doc to hand to the wrapper if he asks

  private int docs_stored; //num of docs pulled from service and cached here.



  //The names we choose for properties is important. Right now, in order to

  //make this proxy compatible with the rest of services in InfoBus, the

  //name of each property should be included in the USMarc.java file. This

  //is because the InfoBus uses a derivative of USMARC as a lingua franca.

  private static String[] supportedProps = new String[1];

  private String[] requestedProps = new String[supportedProps.length];



  // Object that knows how to talk to MapQuest:

  private StreetRouterServer routerinstance;



  // Class constructor

  public CollectionPlug () {



    supportedProps[0] = "Content";

    TheQuery = "";

    numDocs = 0;

    theDocCursor = 0;

    // Here we create an instance of the class that handles the connections

    // with the service, in this example the mapquest directions web server

    routerinstance = new StreetRouterServer();

    return;

  }



  // SetProperties(props)

  // props : list of the names of properties the caller wants

  // included in every returned document. This list must be a subset 

  // of the list of properties supported by this CollectionPlug. If

  // the list is empty, all properties are wanted:



  public void SetProperties (String[] props) 

      throws java.lang.IllegalArgumentException {



    int aux;

    if (props.length == 0) {

      //An empty list means all the properties:

      for(int i=0;i<supportedProps.length;i++) {

        requestedProps[i] = supportedProps[i];

      }

      return;

    }

    // Remember which props we are to return w/ each document:

    // This makes a new array each time, with the assumption that this

    // method won't be called much. If it is, you could null out the 

    // existing array and reuse it:

    requestedProps = new String[props.length];

    for(int i=0;i<props.length;i++) {

      if (!CheckPropAvailability(props[i])) 

        throw new IllegalArgumentException();

      requestedProps[i] = props[i];

    }

    return;

  }



  // GetDefaultPropertyNames()

  // Returns the default set of names of the supported set of properties in the 

  // documents of this CollectionPlug.



  public String[] GetDefaultPropertyNames() {

    return(supportedProps);

  }



  // GetPropertyNames(int IndexDocument)

  // Returns the name of the default set of properties in that particular

  // document



  public String[] GetPropertyNames(int index) {

    // In this example, all the documents in a CollectionPlug have the same

    // set of properties. So, we ignore the index of the document, and

    // call the GetProperties method.



    return(this.GetPropertyNames());

  }



  // GetPropertyNames()

  // Returns the names of the properties that were previously set in a

  // call to SetProperties:



  public String[] GetPropertyNames() {

    return requestedProps;

  }



  public int Search(String query, int maxhits) throws Exception {

    // In this example,

    // query is : fromcity*fromstate*tocity*tostate,

    // as in "Palo Alto*California*Los Angeles*California" 

    // maxhits is how many hits are to be fetched initially



    // Extract the parametres from the single query string and

    // store them into several variables:



    this.TheQuery = query;
    String[] query2 = new String[4];

    int pos = query.indexOf("*");

    query2[0] = query.substring(0,pos);

    query = query.substring(pos + 1, query.length());

    pos = query.indexOf("*");

    query2[1] = query.substring(0,pos);

    query = query.substring(pos + 1, query.length());

    pos = query.indexOf("*");

    query2[2] = query.substring(0,pos);

    query2[3] = query.substring(pos + 1, query.length());



    // Once we've got the corresponding strings, we call the

    // GetRoute method in the "StreetRouterServer" object. 

    // This method returns a string "content"

    // with the directions from one city to the other. If you 

    // are writing a proxy for a database or some other repository,

    // this is where the dirty work of accessing would be done:



    content = routerinstance.GetRoute(query2[0],

				      query2[1], query2[2], query2[3]);



    // Remember how many result hits we have stored locally

    // (In this degenerate example, that is always one:

    this.docs_stored = 1;

    // How many total hits for this query (again: always 1 in this

    // degenerate example:

    this.numDocs = 1;

    this.theDocCursor = 0;

    return(this.numDocs);

  }



  // GetPropertyValues (pointer)

  // The 'pointer' is a pointer to the array of documents found by

  // a previous search. This method returns the value of all the

  // document's properties.



  public String[] GetPropertyValues (int p)

       throws java.lang.ArrayIndexOutOfBoundsException {





    // In this example there is only one document in the CollectionPlug

    // since the service only gives us a single string of street routing

    // directions.



    if (p != 0) throw new ArrayIndexOutOfBoundsException();

    String[] aux = new String[requestedProps.length];



    aux[0] = this.content;

    // One more doc was passed up to the wrapper:

    theDocCursor++;

    return aux;

  }



  // GetPropertyValues (pointer, list of property names)

  // The 'pointer' is a pointer to the array of documents found by

  // Search.

  // This method returns the value of the properties in the list

  // of property names for the document identified by the pointer.



  public String[] GetPropertyValues (int p, String[] propnames)       

     throws java.lang.ArrayIndexOutOfBoundsException, 

            java.lang.IllegalArgumentException {



    //In this example there is only one document in the CollectionPlug

    //since the service only gives us a single string, and we only have

    //one property.



    if (p != 0) throw new ArrayIndexOutOfBoundsException();

    if (!CheckPropAvailability(propnames)) 

      throw new ArrayIndexOutOfBoundsException();



    String[] aux = new String[propnames.length];



    aux[0] = this.content;

    // One more doc was passed up to the wrapper:

    theDocCursor++;

    return aux;



  }



  public int TotalItems() {

    return numDocs;

  }


  public String TheQuery() {
    return TheQuery;
  }



  // Return true if we were not yet asked for all the docs:

  public boolean MoreAvailable() {

    if ((numDocs > 0) && (theDocCursor < numDocs)) return true;

    else return false;

  }



  public int DocCursor () {

    return theDocCursor;

  }





  // CheckPropAvailability (list of property names)

  // Returns true if each property in a list of property names is 

  // supported by this CollectionPlug.



  public static boolean CheckPropAvailability (String[] propList) {

    for (int i=0; i<propList.length; i++)

      if (!CheckPropAvailability(propList[i])) return false;

    return true;

  }



  // CheckPropAvailability(String propName) returns true if that property

  // is supported:



  public static boolean CheckPropAvailability(String propName) {

    for (int i=0; i<supportedProps.length; i++)

      if (supportedProps[i].equalsIgnoreCase(propName)) return true;

    return false;

  }

}