[Javamatch-cvs] javamatch/docs/website javamatch.xml,1.10,1.11

[Walter v. I. <it...@us...>]

Update of /cvsroot/javamatch/javamatch/docs/website
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv27345/docs/website

Modified Files:
	javamatch.xml 
Log Message:
Restructured website

Index: javamatch.xml
===================================================================
RCS file: /cvsroot/javamatch/javamatch/docs/website/javamatch.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** javamatch.xml	13 Sep 2004 13:39:22 -0000	1.10
--- javamatch.xml	14 Sep 2004 13:42:34 -0000	1.11
***************
*** 23,66 ****
      matching objects.
  </p>
! <h2>Example 1: Queries</h2>
      <p>
      Nice those stories, but how does it work in practice? Let me give you an example:
      </p>
      <p>
!     Suppose you have a data structure that maintains a list of camp sites, with the 
!     facilities they provide. With JavaMatch, your web site can offer a "detailed 
!     search" feature, where a user can specify which one of the facilities he wants or 
!     doesn't want on the site.
!     </p>
!     <p>
!     Let's assume a user wants to look for a small, cheap camp site with a swimming pool.
!     The following code defines and executes this match query:
!     </p>
! <pre class="source">QuerySet query = new QuerySet();
! query.addPreferred(new LessThan("size", 100));
! query.addPreferred(new NumberEquals("distanceToSwimmingPool", 0));
! query.addPreferred(new Minimum("priceIndication"));
! 
! List campSites = guide.getCampSites();
! MatchResult matchResult = matchEngine.executeQuery(query, campSites);</pre>
! <p>
!     Class MatchResult contains a list of ResultItem's. A ResultItem consists of a
!     matchedObject, the object that was matched, and a matchValue, an indication of how 
!     good this object matches the specified criteria). The ResultItems are sorted in
!     decreasing order by their matchValue, so the best matching object is the first one
!     in the list.
! </p>
! <p>
!     The full source can be found in the directory examples/camping in the distribution
  </p>
- <h2>Example 2: Results and extensions</h2>
-     <p>
-     The JavaMatch engine is domain-independent, so if I want to look for a certain 
-     second-hand car, I can specify the following query:
-     </p>
  <pre class="source">QuerySet query = new QuerySet();
  query.addRequired(new StringEquals("brand", "BMW"));
- query.addPreferred(new Range("buildYear", 1997, 2002));
  query.addPreferred(new LessThan("price", 10000));
  query.addPreferred(new LessThan("mileage", 80000));
  
--- 23,40 ----
      matching objects.
  </p>
! <h2>Example: Queries</h2>
      <p>
      Nice those stories, but how does it work in practice? Let me give you an example:
      </p>
      <p>
!     Let's suppose there is an application that keeps an inventory of used cars. 
!     This application has a class <i>Car</i>, with methods <i>getBrand()</i>, 
!     <i>getPrice()</i>, ... to retrieve the brand, price, .... <br/>
!     If I want to find a certain car, I can specify the following query:
  </p>
  <pre class="source">QuerySet query = new QuerySet();
  query.addRequired(new StringEquals("brand", "BMW"));
  query.addPreferred(new LessThan("price", 10000));
+ query.addPreferred(new Range("buildYear", 1997, 2002));
  query.addPreferred(new LessThan("mileage", 80000));
  
***************
*** 126,165 ****
  <p>
      As you can see in row 1 to 3, the match engine first returns the objects that 
!     exactly match the criteria. This is similar to the rows you'll get when you
!     execute an SQL query. Row 4 to 6 are different: they show the objects that 
      don't match <b>exactly</b>, but the objects that <b>best</b> match the query.
  </p>
  <hr/>
! <h3>Extensions</h3>
  <p>
!     You may want to find a match with more complicated, domain-specific criteria, 
!     for example if the car has had regular service intervals. In this case, you can 
!     create your own queries by extending class MatchQuery, or one of its subclasses.
!     All you have to do is provide an implementation of <i>getMatchValue</i>, and your 
!     query can be part of the matching process.
!     </p>
! <pre class="source"><i>/**
!  * Class RegularServiceIntervals a query to be used by JavaMatch, 
!  * that checks if a Car has has been services frequently
!  */</i>
! public class RegularServiceIntervals <b>extends MatchQuery</b> {
!     <i>/**
!      * Calculates the regularity of the service intervals
!      * @param matchedObject the car from which the service intervals 
!      *                      are checked
!      * @return an indicator for how regular the car was serviced
!      */</i>
!     <b>public float getMatchValue(Object matchedObject) 
!         throws MatchException {</b>
!         Car carToMatch = (Car)matchedObject;
!         List services = carToMatch.getServices();
!         ... 
!         <i>// calculate and return a value (from 0 to 1, both inclusive)
!         // for how regular the services took place</i>
!     }
! }</pre>
!     <p>
!         More information about extensions can be found in the docs directory in the distribution
!     </p>
  </page>
  <page title="Download/Installation" filebase="download">
--- 100,129 ----
  <p>
      As you can see in row 1 to 3, the match engine first returns the objects that 
!     exactly match the criteria. This is the same data that you get when you execute 
!     a similar SQL query. Row 4 to 6 are different: they show the objects that 
      don't match <b>exactly</b>, but the objects that <b>best</b> match the query.
  </p>
  <hr/>
! <h2>What's more?</h2>
! <p>The queries that you see in the example above are just a small subset of the 
! queries that JavaMatch provides. In the <a href="docs.html">documentation</a> 
! section, you'll find the following different kinds of queries:
! </p>
! <ul>
! <li><a href="docs.html#hierarchy">Queries</a>: Various string, number and boolean 
! queries</li>
! <li><a href="docs.html#relative">Relative matching</a>: Finding minimum and maximum 
! values in the data set</li>
! <li><a href="docs.html#queryset">QuerySets</a>: Used to merge multiple required and/or 
! preferred subqueries</li>
! <li><a href="docs.html#extensions">Extensions</a>: Defining custom queries</li>
! </ul>
  <p>
! Other features provided by JavaMatch are:
! </p>
! <ul>
! <li><a href="docs.html#custom">Customizing</a> the output</li>
! <li><a href="integration.html">Integration</a> with other tools</li>
! </ul>
  </page>
  <page title="Download/Installation" filebase="download">
***************
*** 221,224 ****
--- 185,189 ----
  <p>If you compare the functionality of JavaMatch with SQL, you'll see a couple of
  differences:
+ </p>
  <ul>
  <li>SQL is row-based, JavaMatch is object-oriented</li>
***************
*** 233,237 ****
  matching in the Java runtime environment</li>
  </ul>
- </p>
  <h3>What is JavaMatch, compared to my own search algorithm?</h3>
  <p>
--- 198,201 ----
***************
*** 273,301 ****
  be completed and structured before release 1.0
  </div>
  <p>
! You can browse the <a href="api/index.html" target="_black">API documentation</a> online.
  </p>
  <h2>Matching algorithm</h2>
  <p>The current matching algorithm uses the concept of a <i>query</i> and a list of 
  <i>objects</i> that the query operates on. A typical query is something like 
  <pre>
  If method &lt;m&gt; in object &lt;o&gt; returns a value less than &lt;v&gt; , there is a match&quot;.
  </pre>
  When a query is executed, it returns a value from 0 to 1, both
  inclusive. A 1 means a 100% match, while a 0 return value means a total mismatch.
  </p>
  <p>
! Queries may be combined by using QuerySet-queries. A QuerySet has a list of required
! and a list of preferred subqueries. When all required subqueries match completely, 
! the object that best matches most preferred subqueries returns the highest match value.
  </p>
! <h3>Two-pass queries</h3>
  Some queries, such as Minimum and Maximum, compare an object against all other objects 
! in the object list. These queries are called two-pass queries. In the first pass,
! the relevant data (global minimum and maximum) is calculated. In the second pass, this 
  data is used to calculate the match value. As the name implies, the data is passed twice.
  This means more communication overhead when the data is retrieved from a large database.
! <h2>Match query hierarchy</h2>
! <img src="images/hierarchy.png" alt="Match hierarchy"/>
  <h2>Related technology</h2>
  <h3>Matching engines</h3>
--- 237,360 ----
  be completed and structured before release 1.0
  </div>
+ <h2>API Documentation</h2>
  <p>
! You can browse the <a href="api/index.html">API documentation</a> online. It can also 
! be generated from the <a href="http://sourceforge.net/project/showfiles.php?group_id=116811">
! distribution</a>.
  </p>
  <h2>Matching algorithm</h2>
  <p>The current matching algorithm uses the concept of a <i>query</i> and a list of 
  <i>objects</i> that the query operates on. A typical query is something like 
+ </p>
  <pre>
  If method &lt;m&gt; in object &lt;o&gt; returns a value less than &lt;v&gt; , there is a match&quot;.
  </pre>
+ <p>
  When a query is executed, it returns a value from 0 to 1, both
  inclusive. A 1 means a 100% match, while a 0 return value means a total mismatch.
  </p>
+ <h3><a name="queryset"/>QuerySets</h3>
  <p>
! Queries may be combined by using QuerySet-queries.<br/>
! A QuerySet maintains two different lists: A list of <b>required</b> subqueries 
! and a list of <b>preferred</b> subqueries. During the matching, all required 
! subqueries are first evaluated. When the required subqueries <i>don't</i> match 
! completely, the match is considered a mismatch. When the required queries <i>do</i> 
! match completely, the preferred subqueries are also evaluated. The match value of 
! the QuerySet is calculated by taking the (weighted) average of all subqueries.
! This algorithm returns the highest match value (the highest relative ranking)
! for those objects that have the most / best matching subqueries.
  </p>
! <p>
! A QuerySet is also a MatchQuery. This way, QuerySets may be nested. Escpecially
! when nesting QuerySets, you might want to provide different weights for the nested
! subqueries:
! </p>
! <pre class="source">query.addPreferred(nestedQuery, 4f);</pre>
! <h2><a name="hierarchy"/>Match query hierarchy</h2>
! <map id="hierarchyMap" name="hierarchyMap">
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/RegexMatches.html" alt="RegexMatches" coords="253,265 367,265 367,217 253,217 253,265"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/BooleanEquals.html" alt="BooleanEquals" coords="0,157 121,157 121,109 0,109 0,157"/>   
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/NotQuery.html" alt="NotQuery" coords="262,157 352,157 352,109 262,109 262,157"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/LessThan.html" alt="LessThan" coords="589,374 674,374 674,325 589,325 589,374"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/GreaterThan.html" alt="GreaterThan" coords="457,374 565,374 565,325 457,325 457,374"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/NumberEquals.html" alt="NumberEquals" coords="229,374 349,374 349,325 229,325 229,374"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/Maximum.html" alt="Maximum" coords="121,374 205,374 205,325 121,325 121,374"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/Range.html" alt="Range" coords="373,374 433,374 433,325 373,325 373,374"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/Minimum.html" alt="Minimum" coords="12,374 97,374 97,325 12,325 12,374"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/StringEquals.html" alt="StringEquals" coords="121,265 229,265 229,217 121,217 121,265"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/Contains.html" alt="Contains" coords="12,265 97,265 97,217 12,217 12,265"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/StringQuery.html" alt="StringQuery" coords="133,157 241,157 241,109 133,109 133,157"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/MatchQuery.html" alt="MatchQuery" coords="247,49 355,49 355,0 247,0 247,49"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/QuerySet.html" alt="QuerySet" coords="517,157 601,157 601,109 517,109 517,157"/>
!   <area shape="poly" href="api/net/sourceforge/javamatch/query/NumericQuery.html" alt="NumericQuery" coords="373,157 493,157 493,109 373,109 373,157"/>
! </map>
! <img src="images/hierarchy.png" alt="Match hierarchy" usemap="#hierarchyMap"/>
! <h2><a name="relative"/>Relative matching</h2>
! <p>
  Some queries, such as Minimum and Maximum, compare an object against all other objects 
! in the object list. An example of a two-pass query:
! </p>
! <p>
! Let's assume a user wants to look for a small, cheap camp site with a swimming pool.
! The following code defines and executes this match query:
! </p>
! <pre class="source">QuerySet query = new QuerySet();
! query.addPreferred(new LessThan("size", 100));
! query.addPreferred(new NumberEquals("distanceToSwimmingPool", 0));
! query.addPreferred(new Minimum("priceIndication"));
! 
! List campSites = guide.getCampSites();
! MatchResult matchResult = matchEngine.executeQuery(query, campSites);</pre>
! <p>
! The full source of this example can be found in the directory examples/camping in 
! the distribution
! </p>
! <p>
! This kind of queries is called a two-pass query. In the first pass, the relevant data 
! (global minimum and maximum for the price) is calculated. In the second pass, this 
  data is used to calculate the match value. As the name implies, the data is passed twice.
  This means more communication overhead when the data is retrieved from a large database.
! </p>
! <h2><a name="extensions"/>Extensions</h2>
! <p>
!     You may want to find a match with more complicated, domain-specific criteria, 
!     for example if the car has had regular service intervals. In this case, you can 
!     create your own queries by extending class MatchQuery, or one of its subclasses.
!     All you have to do is provide an implementation of <i>getMatchValue</i>, and your 
!     query can be part of the matching process.
!     </p>
! <pre class="source"><i>/**
!  * Class RegularServiceIntervals a query to be used by JavaMatch, 
!  * that checks if a Car has has been services frequently
!  */</i>
! public class RegularServiceIntervals <b>extends MatchQuery</b> {
!     <i>/**
!      * Calculates the regularity of the service intervals
!      * @param matchedObject the car from which the service intervals 
!      *                      are checked
!      * @return an indicator for how regular the car was serviced
!      */</i>
!     <b>public float getMatchValue(Object matchedObject) 
!         throws MatchException {</b>
!         Car carToMatch = (Car)matchedObject;
!         List services = carToMatch.getServices();
!         ... 
!         <i>// calculate and return a value (from 0 to 1, both inclusive)
!         // for how regular the services took place</i>
!     }
! }</pre>
! <h2><a name="custom"/>Output customization</h2>
! There are several ways to customize JavaMatch's output. These customizations are
! performed on the match engine (class <code>net.sourceforge.javamatch.engine.MatchEngine</code>).
! <hr/>
! <h3>Number of returned results</h3>
! To change the number of results that are returned by JavaMatch, you can call
! <pre class="source">matchEngine.setMaxNumResultItems(<i>&lt;number of items&gt;</i>);</pre>
! <hr/>
! <h3>Match threshold</h3>
! You might want to specify a threshold value: a minimum value before an object is 
! added to the result. This can be done by calling
! <pre class="source">matchEngine.setThreshold(<i>&lt;threshold value&gt;</i>);</pre>
  <h2>Related technology</h2>
  <h3>Matching engines</h3>
***************
*** 324,331 ****
  </ul>
  <h2>Other technologies in depth</h2>
! <a name="sodaquery"/>
! <h3>SodaQuery</h3>
  <p>
! SODAQuery project summary:<br/>
  <i>S.O.D.A. is a an object API to communicate with databases. The current 
  specification is focussed on queries. Goals are: type safety, object reuse, 
--- 383,389 ----
  </ul>
  <h2>Other technologies in depth</h2>
! <h3><a name="sodaquery"/>SodaQuery</h3>
  <p>
! <a href="http://sodaquery.sourceforge.net">SODAQuery</a> project summary:<br/>
  <i>S.O.D.A. is a an object API to communicate with databases. The current 
  specification is focussed on queries. Goals are: type safety, object reuse, 
***************
*** 333,338 ****
  </p>
  <p>
! The main differences and similarities between JavaMatch and 
! <a href="http://sodaquery.sourceforge.net">SODAQuery</a> are:
  </p>
  <p>
--- 391,395 ----
  </p>
  <p>
! The main differences and similarities between JavaMatch and SODAQuery are:
  </p>
  <p>
***************
*** 403,407 ****
  JavaMatch works in combination with such storage mechanisms.
  </p>
! <a name="prevayler"/><h2>Prevayler</h2>
  <p class="intro">
  <a href="http://www.prevayler.org">Prevayler</a> does not use a database. It keeps the entire 
--- 460,464 ----
  JavaMatch works in combination with such storage mechanisms.
  </p>
! <h2><a name="prevayler"/>Prevayler</h2>
  <p class="intro">
  <a href="http://www.prevayler.org">Prevayler</a> does not use a database. It keeps the entire