[Javamatch-cvs] javamatch/src/net/sourceforge/javamatch/query QuerySet.java,NONE,1.1 AndList.java,1.1.1.1,NONE MatchList.java,1.1.1.1,NONE OrList.java,1.1.1.1,NONE

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

Update of /cvsroot/javamatch/javamatch/src/net/sourceforge/javamatch/query
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv30020/query

Added Files:
	QuerySet.java 
Removed Files:
	AndList.java MatchList.java OrList.java 
Log Message:
Replace MatchList, AndList, OrList with QuerySet

--- AndList.java DELETED ---

--- OrList.java DELETED ---

--- MatchList.java DELETED ---

--- NEW FILE: QuerySet.java ---
/* JavaMatch: Matching engine for Java runtime data structures
 * Copyright (C) 2004 Walter van Iterson
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
package net.sourceforge.javamatch.query;

import java.util.*;
import net.sourceforge.javamatch.engine.*;

/**
 * Class QuerySet combines multiple subqueries into a single query. The 
 * subqueries in a QuerySet may be required or preferred. When an object is
 * matched, all required subqueries must match completely, or the QuerySet
 * reports a mismatch. When all required subqueries match, the preferred
 * subqueries determine the match value of the matched object. Preferred 
 * subqueries may be weighted. The match value is the weighted average of 
 * all preferred subqueries.
 */
public class QuerySet extends MatchQuery {
    /** The list of match queries, with their weight, that make up the preferred 
	    part of this QuerySet. They are stored as WeightedMatchQuery-objects, to 
		merge the query and its weight */
    private Vector preferredQueries = new Vector();

	/** The list of match queries that make up the required part of this match 
	    query. These are stored as just the query objects, as required queries 
		don't have a weight factor */
	private Vector requiredQueries = new Vector();

    /**
     * Adds a the given subquery to the list of preferred queries, with a 
	 * default weight (1)
	 * @param query the subquery that is added to the list of preferred queries
     */
    public void addPreferredQuery(MatchQuery query) {
        addPreferredQuery(query, 1f);
    }

    /**
     * Adds a the given subquery to the list of preferred queries, with the 
	 * given weight
	 * @param query the subquery that is added to this MatchList
	 * @param weight the relative weight of this subquery
     */
    public void addPreferredQuery(MatchQuery query, float weight) {
		if (query == null) {
			throw new NullPointerException("Can't add a null query");
		}
        preferredQueries.add(new WeightedMatchQuery(query, weight));
    }

    /**
     * Adds a the given subquery to the list of required queries
	 * @param query the subquery that is added to the list of required queries
     */
    public void addRequiredQuery(MatchQuery query) {
		if (query == null) {
			throw new NullPointerException("Can't add a null query");
		}
		requiredQueries.add(query);
    }

	/**
	 * Returns if this MatchQuery is two-pass. When the query is two-pass, a 
	 * call to prePass will be made for every object, before the matchValue is
	 * requested
	 * @return false if the query is single-pass, true if the query is two-pass
	 */
	public boolean isTwoPass() {
		Iterator queryIterator = preferredQueries.iterator();
		while (queryIterator.hasNext()) {
			MatchQuery curQuery = ((WeightedMatchQuery)queryIterator.next()).getQuery();
			if (curQuery.isTwoPass()) {
				return true;
			}
		}
		queryIterator = requiredQueries.iterator();
		while (queryIterator.hasNext()) {
			MatchQuery curQuery = (MatchQuery)queryIterator.next();
			if (curQuery.isTwoPass()) {
				return true;
			}
		}
        return false;
	}

	/**
	 * Performs the pre-pass of a two-pass query. A MatchList is two-pass if and
	 * only if at least one of its sub-queries is two-pass.
	 * @param matchedObject the object theat is currently matched
	 * @throws MatchException when the prePass failed
	 */
	public void prePass(Object matchedObject) throws MatchException {
		Iterator queryIterator = requiredQueries.iterator();
		while (queryIterator.hasNext()) {
			MatchQuery curQuery = (MatchQuery)queryIterator.next();
			if (curQuery.isTwoPass()) {
				curQuery.prePass(matchedObject);
			}
		}
		queryIterator = preferredQueries.iterator();
		while (queryIterator.hasNext()) {
			MatchQuery curQuery = ((WeightedMatchQuery)queryIterator.next()).getQuery();
			if (curQuery.isTwoPass()) {
				curQuery.prePass(matchedObject);
			}
		}
	}

    /**
	 * Returns the match value of this match query, when executed on the given 
	 * object. 
	 * @param targetObject the object agains which the query is executed
	 * @return A value between 0 and 1, both inclusive, that indicates how good 
	 *         the object matches this query. 0 means a mismatch, 1 means a full
	 *         match
	 * @throws MatchException when the value could not be retrieved
     */
    public float getMatchValue(Object targetObject) throws MatchException {
        Iterator queryIterator = requiredQueries.iterator();
        while (queryIterator.hasNext()) {
			MatchQuery curQuery = (MatchQuery)queryIterator.next();
			if (curQuery.getMatchValue(targetObject) < 1f) {
				return 0f;
			}
		}
        float totalWeight = 0;
        float totalMatchValue = 0;
        queryIterator = preferredQueries.iterator();
        while (queryIterator.hasNext()) {
            WeightedMatchQuery curWeightedQuery = (WeightedMatchQuery)queryIterator.next();
            MatchQuery curQuery = curWeightedQuery.getQuery();
            float itemWeight = curWeightedQuery.getWeight();
            totalWeight += itemWeight;

            float matchValue = curQuery.getMatchValue(targetObject);
            totalMatchValue += matchValue * itemWeight;
        }
        return totalMatchValue / totalWeight;
    }

	/**
	 * Class WeightedMatchQuery combined a match query and its weight
	 */
	class WeightedMatchQuery {
		/** The relative weight of this match query */
		private float weight;
	
		/** The match query */
		private MatchQuery query;
	
		/**
		 * Creates a new WeightedMatchQuery, with the given query and the given 
		 * relative weight
		 * @param query the original subquery
		 * @param weight the relative weight of this subquery
		 */
		public WeightedMatchQuery(MatchQuery query, float weight) {
			this.query = query;
			this.weight = weight;
		}
	
		/**
		 * Returns the query
		 * @return the original subquery
		 */
		public MatchQuery getQuery() {
			return query;
		}
	
		/**
		 * Returns the relative weight of this query
		 * @return the weight of this subquery
		 */
		public float getWeight() {
			return weight;
		}
	}
}