[Javamatch-cvs] javamatch/src/net/sourceforge/javamatch/engine MatchEngine.java,1.1.1.1,1.2 MatchResult.java,1.1.1.1,1.2

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

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

Modified Files:
	MatchEngine.java MatchResult.java 
Log Message:
Add listener mechanism for query started / finished callbacks
Added retrieveObject and discardObject, for access to persistent storage

Index: MatchEngine.java
===================================================================
RCS file: /cvsroot/javamatch/javamatch/src/net/sourceforge/javamatch/engine/MatchEngine.java,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** MatchEngine.java	3 Sep 2004 08:21:21 -0000	1.1.1.1
--- MatchEngine.java	7 Sep 2004 09:41:06 -0000	1.2
***************
*** 27,30 ****
--- 27,39 ----
   */
  public class MatchEngine {
+ 	/** Lock object for adding, removing and notifying listeners */
+ 	private Object listenerLock = new Object();
+ 
+ 	/** The listeners that want to be notified of events */
+ 	private HashSet listeners = new HashSet();
+ 
+ 	/** The maximum number of result items to be returned in a query */
+ 	private int maxNumResultItems = 10;
+ 
  	/**
  	 * Executes the specified match query on all objects in the given List.
***************
*** 46,66 ****
  										   + "on null items");
  		}
  		if (query.isTwoPass()) {
  			Iterator itemIterator = itemsToMatch.iterator();
  			while (itemIterator.hasNext()) {
  				Object curItem = itemIterator.next();
  				query.prePass(curItem);
  			}
  		}
  
! 		MatchResult result = new MatchResult();
  		Iterator itemIterator = itemsToMatch.iterator();
  		while (itemIterator.hasNext()) {
  			Object curItem = itemIterator.next();
  			float matchValue = query.getMatchValue(curItem);
! 			ResultItem resultItem = new ResultItem(curItem, matchValue);
! 			result.addResultItem(resultItem);
  		}
  		return result;
  	}
  }
--- 55,173 ----
  										   + "on null items");
  		}
+ 		notifyListenersStarted(query);
  		if (query.isTwoPass()) {
  			Iterator itemIterator = itemsToMatch.iterator();
  			while (itemIterator.hasNext()) {
  				Object curItem = itemIterator.next();
+ 				curItem = retrieveObject(curItem);
  				query.prePass(curItem);
+ 				discardObject(curItem);
  			}
  		}
  
! 		MatchResult result = new MatchResult(this);
! 		result.setMaxNumResultItems(maxNumResultItems);
  		Iterator itemIterator = itemsToMatch.iterator();
  		while (itemIterator.hasNext()) {
  			Object curItem = itemIterator.next();
+ 			curItem = retrieveObject(curItem);
  			float matchValue = query.getMatchValue(curItem);
! 			// discarding is done by the MatchResult, as it knows when an object 
! 			// is not in the top 10 any more
! 			result.addResultItem(curItem, matchValue);
  		}
+ 
+ 		notifyListenersFinished(query, result);
  		return result;
  	}
+ 
+ 	/** 
+ 	 * Retrieves and returns the object or object with the given identifier from 
+ 	 * the underlying persistent storage mechanism, if any. By default, returns 
+ 	 * the same object.	This method notifies the registered listeners that the
+ 	 * object has been retrieved
+ 	 * @param objectToRetrieve the object or object identifier to retrieve
+ 	 * @return the object that is retrieved
+ 	 */
+ 	// throws an exception when data retrieval failed?
+ 	protected Object retrieveObject(Object objectToRetrieve) {
+ 		// don't do anything in the default implementation, objects are already
+ 		// in memory
+ 		return objectToRetrieve;
+ 	}
+ 
+ 	/** 
+ 	 * Discards the given object from memory. After discarding, the match engine 
+ 	 * will not call this object again (the calling application might still do 
+ 	 * so, but that's up to that application. This method notifies the 
+ 	 * registered listeners that the object is about to be discarded
+ 	 * @param objectToDiscard the object to discard
+ 	 */
+ 	// throws an exception when discarding failed?
+ 	protected void discardObject(Object objectToDiscard) {
+ 		// don't do anything in the default implementation, objects are kept in 
+ 		// memory
+ 	}
+ 
+ 	/**
+ 	 * Registers the givem match listener to receive notifications when events
+ 	 * occur in this match engine
+ 	 * @param listener the listener that is registered to be notified of events
+ 	 */
+ 	public void addMatchListener(MatchListener listener) {
+ 		if (listener == null) {
+ 			throw new NullPointerException("Can't add a null match listener");
+ 		}
+ 		synchronized (listenerLock) {
+ 			if (listeners.contains(listener)) {
+ 				throw new IllegalArgumentException("Can't add a listener that "
+ 												   + "is already added");
+ 			}
+ 			listeners.add(listener);
+ 		}
+ 	}
+ 
+ 	/**
+ 	 * Unregisters the given match listener from notifications when events occur
+ 	 * in this match engine
+ 	 * @param listener the listener that is unregistered from notifications
+ 	 */
+ 	public void removeMatchListener(MatchListener listener) {
+ 		if (listener == null) {
+ 			throw new NullPointerException("Can't remove a null match listener");
+ 		}
+ 		synchronized (listenerLock) {
+ 			if (!listeners.contains(listener)) {
+ 				throw new IllegalArgumentException("Can't remove a listener " +
+ 												   "that hasn't been added");
+ 			}
+ 			listeners.remove(listener);
+ 		}
+ 	}
+ 
+ 	/**
+ 	 * Notifies the registered listeners that a match query is started
+ 	 */
+ 	private void notifyListenersStarted(MatchQuery query) {
+ 		synchronized (listenerLock) {
+ 			Iterator listenerIterator = listeners.iterator();
+ 			while (listenerIterator.hasNext()) {
+ 				MatchListener curListener = (MatchListener)listenerIterator.next();
+ 				curListener.matchQueryStarted(query);
+ 			}
+ 		}
+ 	}
+ 
+ 	/**
+ 	 * Notifies the registered listeners that a match query has finished
+ 	 */
+ 	private void notifyListenersFinished(MatchQuery query, MatchResult result) {
+ 		synchronized (listenerLock) {
+ 			Iterator listenerIterator = listeners.iterator();
+ 			while (listenerIterator.hasNext()) {
+ 				MatchListener curListener = (MatchListener)listenerIterator.next();
+ 				curListener.matchQueryFinished(query, result);
+ 			}
+ 		}
+ 	}
  }

Index: MatchResult.java
===================================================================
RCS file: /cvsroot/javamatch/javamatch/src/net/sourceforge/javamatch/engine/MatchResult.java,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** MatchResult.java	3 Sep 2004 08:21:21 -0000	1.1.1.1
--- MatchResult.java	7 Sep 2004 09:41:06 -0000	1.2
***************
*** 31,41 ****
      private ArrayList resultItems;
  
! 	/** The maximm number of result items in this MatchResult */
  	private int maxNumResultItems = DEFAULT_NUM_RESULT_ITEMS;
  
  	/**
  	 * Creates a new MatchResult
  	 */
! 	public MatchResult() {
  		resultItems = new ArrayList();
  	}
--- 31,45 ----
      private ArrayList resultItems;
  
! 	/** The maximum number of result items in this MatchResult */
  	private int maxNumResultItems = DEFAULT_NUM_RESULT_ITEMS;
  
+ 	/** The match engine, used to discard objects that roll out of the result */
+ 	private MatchEngine matchEngine;
+ 
  	/**
  	 * Creates a new MatchResult
  	 */
! 	public MatchResult(MatchEngine matchEngine) {
! 		this.matchEngine = matchEngine;
  		resultItems = new ArrayList();
  	}
***************
*** 49,55 ****
  	 * @param resultItem the result item to be added
       */
!     public void addResultItem(ResultItem resultItem) {
! 		if (resultItem == null) {
! 			throw new NullPointerException("Can't add null result item");
  		}
  		int numItems = resultItems.size();
--- 53,59 ----
  	 * @param resultItem the result item to be added
       */
!     public void addResultItem(Object matchedObject, float matchValue) {
! 		if (matchedObject == null) {
! 			throw new NullPointerException("Can't add null matched object");
  		}
  		int numItems = resultItems.size();
***************
*** 58,66 ****
  		if (numItems == maxNumResultItems) { 
  			Object lastObject = resultItems.get(numItems - 1);
! 			if (resultItem.getMatchValue() <= ((ResultItem)lastObject).getMatchValue()) {
  				return;
  			}
  		}
  		// find position and insert
  		int insertIndex = Collections.binarySearch(resultItems, resultItem);
  		if (insertIndex >= 0) {
--- 62,72 ----
  		if (numItems == maxNumResultItems) { 
  			Object lastObject = resultItems.get(numItems - 1);
! 			if (matchValue <= ((ResultItem)lastObject).getMatchValue()) {
! 				matchEngine.discardObject(matchedObject);
  				return;
  			}
  		}
  		// find position and insert
+ 		ResultItem resultItem = new ResultItem(matchedObject, matchValue);
  		int insertIndex = Collections.binarySearch(resultItems, resultItem);
  		if (insertIndex >= 0) {
***************
*** 70,74 ****
  		}
  		if (resultItems.size() > maxNumResultItems) {
! 			resultItems.remove(maxNumResultItems);
  		}
      }
--- 76,81 ----
  		}
  		if (resultItems.size() > maxNumResultItems) {
! 			Object removedObject = resultItems.remove(maxNumResultItems);
! 			matchEngine.discardObject(removedObject);
  		}
      }