Updated Oct 10, 2009 by john.wang
Labels:	Featured, Phase-Implementation

GettingStarted

Getting Started:

Prepare a browse index:

A browse index is a Lucene index with field description information. Bobo Browse does not currently provide any extensive indexing wrappers on top of Lucene, so indexing with the standard Lucene API (http://lucene.apache.org/java/2_4_1/api/core/index.html) would suffice.

See Creating a Browse Index for details.

Search and Browse:

The Bobo Browse Engine is released as a library, the API is published here. Familiarity with the Lucene API is helpful.

Here are some of the basic concepts or objects to understand:

BrowseSelection: A selection or filter to be applied, e.g. Color=Red
FacetSpec: Specifies how facets are to be returned on the result object, e.g. Top 10 facets of car types ordered by count with a min count of 5
BrowseRequest: A set of BrowseSelections, a keyword text query, and a set of FacetSpecs.
BrowseFacet: a facet, (a string value with a hit count)
FacetCollection: A Collection object of BrowseFacets
BrowseResult: Result of a browse operation.
FacetHandler: A plugin into the browse engine to knows how to manipulate facet data.
BoboIndexReader: A Lucene IndexReader containing a List of FacetHandlers.

Example:

// define facet handlers
	  
	    // color facet handler
	    SimpleFacetHandler colorHandler = new SimpleFacetHandler("color");
	    
	    // category facet handler
	    SimpleFacetHandler categoryHandler = new SimpleFacetHandler("category");
	    
	    List<FacetHandler> handlerList = Arrays.asList(new FacetHandler[]{colorHandler,categoryHandler});
	    
		// opening a lucene index
		  Directory idx = FSDirectory.open(new File("myidx"));
		  IndexReader reader = IndexReader.open(idx,true);
		   
		  // decorate it with a bobo index reader
		  BoboIndexReader boboReader = BoboIndexReader.getInstance(reader,handlerList);
		   
		  // creating a browse request
		  BrowseRequest br=new BrowseRequest();
		  br.setCount(10);
		  br.setOffset(0);
		   
		  // add a selection
		  BrowseSelection sel=new BrowseSelection("color");
		  sel.addValue("red");
		  br.addSelection(sel);
		   
		  // parse a query
		  QueryParser parser = new QueryParser("contents",new StandardAnalyzer(Version.LUCENE_CURRENT));
		  Query q=parser.parse("cool car");
		  br.setQuery(q);
		   
		  // add the facet output specs
		  FacetSpec colorSpec = new FacetSpec();
		  colorSpec.setOrderBy(FacetSortSpec.OrderHitsDesc);
		   
		  FacetSpec categorySpec = new FacetSpec();
		  categorySpec.setMinHitCount(2);
		  categorySpec.setOrderBy(FacetSortSpec.OrderHitsDesc);
		   
		  br.setFacetSpec("color",colorSpec);
		  br.setFacetSpec("category",categorySpec);
		   
		  // perform browse
		  Browsable browser=new BoboBrowser(boboReader);
		  BrowseResult result=browser.browse(br);
		   
		  int totalHits = result.getNumHits();
		  BrowseHit[] hits = result.getHits();
		   
		  Map<String,FacetAccessible> facetMap = result.getFacetMap();
		   
		  FacetAccessible colorFacets = facetMap.get("color");
		  List<BrowseFacet> facetVals = colorFacets.getFacets();

Comment by mathieu.durand, Sep 22, 2009

I tried this code but it only worked when I passed some FacetHandlers? to the BoboIndexReader?.getInstance. Am I missing something ?

Comment by john.wang, Sep 25, 2009

That's correct. You either have to pass it in or have a bobo.spring define the facet handlers in the index.

Comment by tommyng2009, Oct 08, 2009

What would be the best way to display result? get documentId out of every BrowseHit?, then get the Lucene Document? When I tried to get the data directly out of BrowseHit? with getField, it gave me null pointer exception. I am using Lucene 2.9.0 and Bobo Browsing 2.0.6

Code Sample: BrowseHit? hits = result.getHits(); for(int i=0;i<hits.length;++i) {

BrowseHit? browseHit = hitsi?; Document d = reader.document(browseHit.getDocid()); System.out.println(d.get("color"));

} Is it the only way to display result?

Comment by john.wang, Oct 10, 2009

we don't currently support lucene 2.9.0 (we do have a branch for lucene2.9 migration however, still working on it though)

one reason you are getting a NPE is because on the BrowseRequest?, you are not requesting field values. Do: BrowseRequest?.setFetchStoredFields(true)

We should probably throw a better exception.

Comment by john.wang, Oct 10, 2009

Actually, if you have "color" already defined in a FacetHandler, you don't need to call setFetchStoredFields.

Comment by john.wang, Oct 10, 2009

I updated the wiki with a better code snippet

Comment by tommyng2009, Oct 21, 2009

Hi John, Thanks for your quick reply. Your new snippet update and your explanation really got me 80% there. However, I still have alittle problem left. Since its a longer question, I sent you an email regarding the problem. Your help is truely appreciated.

Comment by finalfantasy22, Oct 21, 2009

Any one knows why I always get java.lang.OutOfMemoryError?: Java heap space at line BrowseResult? result=browser.browse(br) - for about 3-4 SimpleFacetHandler? on about 5,000,0000 documents search ?

Comment by dipl.inf.matthias.schmidt, Oct 27, 2009

Honestly guys, you need far more documentation here!

I coming from the Solr corner searching for a technology to implement a faceted browser in a standalone Java application. All I get downloading the release is the sources jar-file and the online JavaDoc? isn't working...

Please provide new users by giving a step-by-step tutorial about how to install and start, give some more code examples and more conceptual information.