source: trunk/java-client/org/nzdl/gsdl/service/NzdlResultSet.java@ 2285

/*
 *    NzdlResultSet.java
 *    Copyright (C) 2001 New Zealand Digital Library Project
 *
 *    This program is free software; you can redistribute it and/or modify
 *    it under the terms of the GNU General Public License as published by
 *    the Free Software Foundation; either version 2 of the License, or
 *    (at your option) any later version.
 *
 *    This program 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 General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program; if not, write to the Free Software
 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

//the package we're in
package org.nzdl.gsdl.service;

import java.util.Set;
import java.util.Map;
import java.util.List;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.ListIterator;
import java.util.Iterator;

/**
 * An object that holds results extracted from a response by
 * {@link NzdlResponse#getResultSet() NzdlResponse.getResultSet()}.
 * Easily interrogated by a user.
 * @author Stuart Yeates  ([email protected])
 * @author Aziz Mahoui    ([email protected])
 * @author Gordon Paynter ([email protected])
 * @author Brett Sheeran ([email protected]) (comments)
 */
public class NzdlResultSet extends java.lang.Object {

  private List m_resultSet   = null;
  private long m_numDocs     = -1;
  private long m_resultType  = -1;
  private List m_queryTerms  = null;
  private List m_docIDs = null;

  /* The key is the query term, the value its frequency */
  private Map m_frequencies = null;

  /*
   * The key is the docID, the value is the doc corresponding
   * meta data which is also a Map where the key is the meta tag
   * and the value is a set of values for that tag
   */
  private Map m_docToMetaDataMap = null;

  /**
   * Creates an empty instance of NzdlResultSet.
   */
  public NzdlResultSet() {
    m_resultSet = new ArrayList();
    m_docToMetaDataMap = new HashMap();
    m_docIDs = new ArrayList();
  }

  public String getTermFrequencyString() {
    StringBuffer buf = new StringBuffer();
    Iterator iter = m_frequencies.keySet().iterator();
    while(iter.hasNext()) {
      Object next = iter.next();
      buf.append(' ').append(next).append(':').
    append(m_frequencies.get(next));
    }
    return buf.toString();
  }

  /**
   * Adds a {@link NzdlQueryHit NzdlQueryHit} to a result set.
   * @param hit - is an instance of NzdlQueryHit.
   */
  public void add( NzdlQueryHit _hit ) {
    m_resultSet.add( _hit ) ;
    String id = _hit.getDocumentID();
    m_docIDs.add( id );
    m_docToMetaDataMap.put( id, _hit.getMetaData() );
  }

    /**
   * Sets the number of documents in a NzdlResultSet.
   * @param num the number of documents in the result set
   */
  public void setNumOfDocs( long _num ) {
    m_numDocs = _num;
  }


  /**
   * Sets the result type.
   * @param type an integer representing the result type.
   */
  public void setResultType( long _type ) {
    m_resultType = _type;
  }

  /**
   * Sets the Query terms of a NzdlResultSet.
   * @param terms a list of words within the query string.
   */
  public void setQueryTerms( List _terms ) {
    m_queryTerms = _terms;
  }

//    public void setTermFrequency( String _term, int _freq ) {
//      m_frequencies.put( _term, new Integer(_freq) );
//    }

  /**
   * Sets the term frequencies within a NzdlResultSet.
   * @param freqs a map of the term frequencies. The map key is the query term.
   */
  public void setTermFrequencies( Map _freqs ) {
    m_frequencies = _freqs;
  }

  /**
   * Returns the number of documents that matched a query. <br>
   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
   * {@link NzdlService NzdlService} object has filled the NzdlResponse
   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
   * @return The number of documents that matched a query. This is limited
   * by the maxDocs set in {@link NzdlQuery NzdlQuery}
   */
  public long getNumOfDocs() {
    return m_numDocs;
  }

  /**
   * Returns the result type for the NzdlResultSet. <br>
   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
   * {@link NzdlService NzdlService} object has filled the NzdlResponse
   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
   * @return result type as an integer.
   */
  public long getResultType() {
    return m_resultType;
  }

  /**
   * Returns a list of the words within the query string. <br>
   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
   * {@link NzdlService NzdlService} object has filled the NzdlResponse
   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
   * @return A list of words within the query string.
   */
  public List getQueryTerms() {
    return m_queryTerms;
  }

   /**
   * Returns the number of hits for each word within the query string. <br>
   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
   * {@link NzdlService NzdlService} object has filled the NzdlResponse
   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
   * @return A map of the frequency of each query word. The map key is the query term..
   */
  public Map getTermFrequencies() {
    return m_frequencies;
  }
  
//    public int getTermFrequency( String _term ) {
//      return ((Integer)m_frequencies.get(_term)).intValue();
//    }

//    public List getDocumentIDs() {
//      NzdlQueryHit hit = null;
//      //Set docIDs = new HashSet();
//      List docIDs = new ArrayList();
//      for (ListIterator itr = m_resultSet.listIterator(); itr.hasNext(); ) {
//        hit = (NzdlQueryHit) itr.next();
//        docIDs.add( hit.getDocumentID() );
//      }
//      return docIDs;
//    }

  /**
   * Returns a list of Document ID's in the NzdlResultSet. <br>
   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
   * {@link NzdlService NzdlService} object has filled the NzdlResponse
   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
   * @return A list of Document ID's in the NzdlResultSet.
   */
    public List getDocumentIDs() {
      return m_docIDs;
    }

//    public Set getMetaData( String _docID, String _metaTag ) {
//      NzdlQueryHit hit = null;
//      for (ListIterator itr = m_resultSet.listIterator(); itr.hasNext(); ) {
//        hit = (NzdlQueryHit) itr.next();
//        if ( _docID.equals( hit.getDocumentID() ) ) {
//      return hit.getMetaDataValues( _metaTag );
//        }
//      }
//      return null;
//    }

  /**
   * Returns metatag values for a document. <br>
   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
   * {@link NzdlService NzdlService} object has filled the NzdlResponse
   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
   * @return A map of metatag values in the specified document. The map key
   * is the metatag field such as Author or Title.
   */
  public Set getMetaData( String _docID, String _metaTag ) {
    Map metaData = (Map) m_docToMetaDataMap.get( _docID );
    if (metaData != null)
      return (Set) metaData.get( _metaTag );
    else
      return new HashSet();
  }

  /**
   * Returns all values for a particular metatag in the result set. <br>
   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
   * {@link NzdlService NzdlService} object has filled the NzdlResponse
   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
   * @param metaTag Descriptive data such as Author, Title or Date.
   * @return A map of all values for a particular metatag in all documents
   * in the NzdlResultSet. The map key is document ID.
   */
  public Map getMetaData( String _metaTag ) {
    Map metaData = new HashMap();
    for (ListIterator itr = m_resultSet.listIterator(); itr.hasNext(); ) {
      NzdlQueryHit hit = (NzdlQueryHit) itr.next();
      metaData.put( hit.getDocumentID(), hit.getMetaDataValues(_metaTag) );
    }
    return metaData;
  }

  /**
   * Returns all values for all metatags in the result set. <br>
   * Pre: A {@link NzdlResponse NzdlResponse} object has been created. A
   * {@link NzdlService NzdlService} object has filled the NzdlResponse
   * object with results from servicing a {@link NzdlRequest NzdlRequest}.<br>
   * @return The metatag values for all metatags in all documents
   * in the NzdlResultSet. The map key is document ID.
   */
  public Map getAllMetaData( ) {
    return m_docToMetaDataMap;
  }

}