Ehcache (2.9.x)-API Developer Guide, searching a Cache

About searching

The Search API allows you to execute arbitrarily complex queries against caches. The development of alternative indexes on values provides the ability for data to being looked up based on multiple crite Ria instead of just keys.

Note:terracotta BigMemory Go and BigMemory Max products use indexing. The search API queries Open-source Ehcache using a direct Search method. For more information on indexing, see Best practices for optimizing searches.

searchable attributes can is extracted from both keys and values. Keys, values, or summary values (aggregators) can all be returned. Here's a simple example:search for 32-year-old males and return the cache values.

Results Results = cache.createquery (). Includevalues ()        . Addcriteria(Age.eq (+) and (Gender.eq ("male")) ). Execute ();

You can formulate queries using the Search API.

attribute<integer> age = Cache.getsearchattribute ("Age");   Person.createquery (). Addcriteria (age.gt). Includevalues (). Execute ();

before creating a query, the cache configuration must is prepared as described in Making a cache searchable .

• For more information about creating queries using the Search API, see Creating a Query.

What is searchable?

searches can performed against Element keys and values, but they must is treated as attributes. Some Element keys and values are directly searchable and can simply is added to the search index as attributes. Some Element keys and values must be made searchable by extracting attributes with supported search types out of the keys and values. It's the attributes themselves that's searchable.

Making a Cache searchable

Caches can made searchable, on a per cache basis, either by configuration or programmatically.

by Configuration

Caches is made searchable by adding a <searchable/> tag to the cache definition in the ehcache.xml file.

<Cachename= "Cache2"Maxbyteslocalheap= "16M"Eternal= "true"Maxbyteslocaloffheap= "256M">     <PersistenceStrategy= "Localrestartable"/>     <searchable/> </Cache>

This configuration would scan keys and values and, if they is of supported search types, add them as attributes called "Key" and "value," respectively. If You don't want automatic indexing of keys and values, you can disable it using:

 <  cache  name  = "CacheName"   ...      >  <  searchable  keys  = "false"   values  = "false"  >   ...  </ searchable  >  </ cache  >  

You might want to does this if you have a mix of types for your keys or values. The automatic indexing would throw an exception if types is mixed.

If you think so you'll want to add search attributes after the cache was initialized, you can explicitly indicate the D Ynamic search configuration. Set the allowdynamicindexing attribute to ' true ' to enable use of the Dynamic Attributes extractor. For more information on the Dynamic Attributes extractor, see defining Attributes.

 <  cache  name  = "CacheName"   ...      >  <  searchable  allowdynamicindexing  = "true"  >   ...  </ searchable  >  </ cache  >  

Often keys or values are not being directly searchable and instead you'll need to extract searchable attributes from T He keys or values. The following example shows a more typical case. Attribute Extractors is explained in + detail in defining Attributes.

<Cachename= "Cache3"Maxentrieslocalheap= "10000"Eternal= "true"Maxbyteslocaloffheap= "10G">     <PersistenceStrategy= "Localrestartable"/>     <searchable>         <Searchattributename= "Age"class= "Net.sf.ehcache.search.TestAttributeExtractor"/>         <Searchattributename= "Gender"expression= "Value.getgender ()"/>     </searchable> </Cache>

Programmatically

The following example shows how to programmatically create the cache configuration with search attributes.

Configuration Cachemanagerconfig =NewConfiguration (); Cacheconfiguration CacheConfig=NewCacheconfiguration ("Mycache", 0). Eternal (true); Searchable searchable=Newsearchable (); cacheconfig.addsearchable (searchable);//Create attributes to use in queries.Searchable.addsearchattribute (NewSearchattribute (). Name ("Age"));//Use a expression for accessing values.Searchable.addsearchattribute (NewSearchattribute (). Name ("first_name"). Expression ("Value.getfirstname ()")); Searchable.addsearchattribute (NewSearchattribute (). Name ("last_name"). Expression ("Value.getlastname ()")); Searchable.addsearchattribute (NewSearchattribute (). Name ("Zip_Code"). ClassName ("Net.sf.ehcache.search.TestAttributeExtractor")); CacheManager=NewCacheManager (cachemanagerconfig); Cachemanager.addcache (NewCache (cacheconfig)); Ehcache Mycache= Cachemanager.getehcache ("Mycache");//Now create the attributes and queries, then execute....

To learn more on the Search API, see the net.sf.ehcache.search* packages in the Ehcache Javadoc.

Defining Attributes

In addition to configuring a cache to is searchable, you must define the attributes-be used in searches.

Attributes is extracted from the keys or values during search by using Attributeextractors. An extracted attribute mustis one of the following types:

• Boolean
• Byte
• Character
• Double
• Float
• Integer
• Long
• Short
• String
• Java.util.Date
• Java.sql.Date
• Enum

These types correspond to the AttributeType enum specified by the Ehcache Javadoc at HTTP://EHCACHE.ORG/APIDOCS/2.9/NET/SF /ehcache/search/attribute/attributetype.html.

Type name matching is case sensitive. For example, a double resolves to the Java.lang.Double class type, and a double is interpreted as the primitive double type.

Search API Example

< searchable >     <  name= "Age"  type= "Integer"/></  Searchable>

If An attribute cannot was found or is of the wrong type, an attributeextractorexception is thrown on search execution. !

Note:on the first use of a attribute, the attribute type is detected, validated against supported types, and saved Autom Atically. Once the type is established and it cannot be changed. For example, if a integer value was initially returned for attribute named ' age ' by the attribute extractor, it's an err Or for the extractor-return a float for this attribute later on.

Well-known Attributes

The

The parts of an Element is well-known attributes can is referenced by some predefined, well-known names. if a key and/or value is a supported search type, it's added automatically as an attribute with the name "key" or "VA Lue. " These well-known attributes has the convenience of being constant attributes made available in the query.key . For even greater readability, statically import so, in this example, your would use key .

well-known Attribute Name	Attribute Constant
Key	Query.key
Value	Query.value

Reflection Attribute Extractor

The Reflectionattributeextractor is a built-in search attribute extractor that uses JavaBean conventions and also unde Rstands a simple form of expression. Where a JavaBean property was available and it is of a searchable type, it can be declared:

 <  cache    >  <  searchable      >  <  searchattribute  name  = "Age"    />  </ searchable  >  </ cache  >  

The expression language of the Reflectionattributeextractor also uses method/value dotted expression chains. The expression chain must start with "key", "value", or "element". From the starting object, a chain of method calls or field names follows. Method calls and field names can be freely mixed in the chain:

<Cache>   <searchable>     <Searchattributename= "Age"expression= "Value.person.getAge ()"/>   </searchable> </Cache> <Cache>   <searchable>      <Searchattributename= "Name"expression= "element.tostring ()"/>   </searchable> </Cache>

Note:the method and field name portions of the expression is case-sensitive.

Custom Attribute Extractor

In further complex situations, you can create your own attribute extractor by implementing the Attributeextractor in Terface. The interface ' s attributefor () method returns the attribute value for the element and attribute name of you specify.

Note:these examples assume there is previously created person objects containing attributes such as name, age, and Gende R.

Provide your extractor class:

<Cachename= "Cache2"Maxentrieslocalheap= "0"Eternal= "true">   <PersistenceStrategy= "None"/>   <searchable>      <Searchattributename= "Age"class= "Net.sf.ehcache.search.TestAttributeExtractor"/>   </searchable> </Cache>

Ehcache (2.9.x)-API Developer Guide, searching a Cache