com.marringtons.object
Class Search

java.lang.Object
  com.marringtons.object.Search

public class Search

extends Object

Search is used to create a database search instance for finding persistent objects by their indexes.

 Search search = Database.search( new MyDAO());
 for ( MyDAO dao = (MyDAO) search.first("my key"); dao != null; dao = (MyDAO) search.next())
   processDAO(dao);
 

Method first() has overloaded methods to accept an int, String or an Index. The first two look for the first DAO index with one field of type int or String. For more complex indexes, or for any but the first int or String, provide an instance of the index class from your DAO.

 
   MyDAO.PrimaryIndex index = new MyDAO.PrimaryIndex;
   index.integer = 32;
   index.string = "my key";
   if (dao = (MyDAO) search.first( index)) gotIt( dao);
  
 

Lazy Loading

A DAO as an inner element of a DAO (single field or array) will normally be loaded as soon as you ask for an item. In some cases this may be more than you need and expensive at that. The Database.search() method has an overloaded form that take a boolean. Set this to true and lazy loading is turned on for this search. The item you search for is loaded as usual, but any DAO relational objects inside are not loaded - just their location is saved. If you later want to access these items, precede access with a call to load() to retrieve the full object. Lazy loading extends to arrays, Collections and Maps, so use load() for all items if lazy is true.

 Search search = new Search().readOnly().lazyLoad();
 daoWithField = (TestDAOfield) search.first(2001, true, true);
 assertTrue(daoWithField.testDAO.string == null);
 TestDAO innerDAO = (TestDAO) daoWithField.testDAO.load();
 assertTrue(innerDAO.equals(daoWithField.testDAO)); // both have same currentRecord
 assertTrue(innerDAO.string == "test DAO fields");
 

Author:

Paul Marrington

Nested Class Summary

static class	Search.Access Static fields in this class are used as part of Search initialisation to define whether data retrieved is only for perusal or whether it can be updated.
static class	Search.Load Static fields in this class are used as part of Search initialisation to define whether loading from the search is to be lazy or eager.

Constructor Summary

Search(Class daoClass, Search.Load load, Search.Access access)
Create a search object for retrieving specified objects from the database.

Search(DAO dao, Search.Load load, Search.Access access)
Create a search object for retrieving specified objects from the database.

Method Summary

DAO	first(Index index) Retrieve the first of a list of objects that match the provided index.
DAO	first(int integerIndex) Retrieve the first of a list of objects that match the provided integer index.
DAO	first(String stringIndex) Retrieve the first of a list of objects that match the provided string index.
DAO	next() Retrieve the next matching record.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Search

public Search(DAO dao,
              Search.Load load,
              Search.Access access)

Create a search object for retrieving specified objects from the database.

Parameters:

dao - instanceof the DAO we will be searching for.

load - Use Search.Load.lazy to not load sub-DAOs (until load() called). Otherwise use Search.Load.eager and all DAOs in the tree will be loaded at the same time. The first is more efficient with deep data structures, but requires code that calls load() before accessing DAO data. The latter is way more convenient - and should be used in most cases without a large data tree.

access - Use Search.Access.readOnly where possible. There is a minor performance benefit - but the main gain is confidence that the database copy cannot be changed. For data that you expect change, use Search.Access.readWrite.

Search

public Search(Class daoClass,
              Search.Load load,
              Search.Access access)

Create a search object for retrieving specified objects from the database.

Parameters:

daoClass - Class for the DAO we will be searching for.

load - Use Search.Load.lazy to not load sub-DAOs (until load() called). Otherwise use Search.Load.eager and all DAOs in the tree will be loaded at the same time. The first is more efficient with deep data structures, but requires code that calls load() before accessing DAO data. The latter is way more convenient - and should be used in most cases without a large data tree.

access - Use Search.Access.readOnly where possible. There is a minor performance benefit - but the main gain is confidence that the database copy cannot be changed. For data that you expect change, use Search.Access.readWrite.

Method Detail

first

public DAO first(Index index)
          throws IOException

Retrieve the first of a list of objects that match the provided index. All sub-components are also loaded. Same as first( index, readOnly, false).

Parameters:

index - being inner class of objectClass

Returns:

DAO object or null if not found

Throws:

IOException

See Also:

next()

first

public DAO first(int integerIndex)
          throws IOException

Retrieve the first of a list of objects that match the provided integer index. The indexes are scanned for the first one that holds a single integer - and that one is used. All sub-components are also loaded. Same as first( index, false).

Parameters:

integerIndex - integer to key item on.

Returns:

DAO object or null if not found

Throws:

IOException

See Also:

next()

first

public DAO first(String stringIndex)
          throws IOException

Retrieve the first of a list of objects that match the provided string index. The indexes are scanned for the first one that holds a single String - and that one is used. All sub-components are also loaded. Same as first( index, false).

Parameters:

stringIndex - string to key item on in index.

Returns:

DAO object or null if not found

Throws:

IOException

See Also:

next()

next

public DAO next()
         throws IOException

Retrieve the next matching record.

Returns:

DAO object or null if no more

Throws:

IOException