~ Licensed to the Apache Software Foundation (ASF) under one
~ or more contributor license agreements.  See the NOTICE file
~ distributed with this work for additional information
~ regarding copyright ownership.  The ASF licenses this file
~ to you under the Apache License, Version 2.0 (the
~ "License"); you may not use this file except in
~ compliance with the License.  You may obtain a copy of the License at
~
~    http://www.apache.org/licenses/LICENSE-2.0
~
~ Unless required by applicable law or agreed to in writing,
~ software distributed under the License is distributed on an
~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~ KIND, either express or implied.  See the License for the
~ specific language governing permissions and limitations
~ under the License.

===================
EclipseLink Caching
===================

EclipseLink has (at least) two different types of caches that it utilizes -- a "shared cache" aka "object cache" aka
"entity cache" and a "query cache".  The shared cache is where entities are cached using their primary key -- with a
default size of 100 objects per entity type. The query cache is where the results of queries for entities are cached
using a combination of the query and the parameters.

Note however that the query cache is (as I understand it) in no way tied to the shared cache -- meaning that if you have data
stored in the query cache, and you update an entity with new data -- the data in the query cache doesn't change.  There are
policies you can configure on the query cache for expiring cached query results but it's still a separate cache from the
shared cache and the two don't seem to be connected or know about each other.  By default, query results are not placed into
the query cache -- you have to enable that explicitly (which can be achieved in a a number of different ways).

There is also a way to get queries to utilize the shared cache which is really nice because then changes to the entities
in the shared cache are resulted in the cached query results (since the cached query results reference entities in the shared
cache).

The way I've gone about enabling query result caching is to use query hints on our named queries.  The query hints to use are
found in the following EclipseLink object:

http://www.eclipse.org/eclipselink/api/2.0/org/eclipse/persistence/config/QueryHints.html

Note that using the QueryHints.CACHE_USAGE hint is how you enable query result caching against the shared cache, while using
the QueryHints.QUERY_RESULTS_CACHE hint is used to enable the query cache.  When using the query cache there are also other
hints available for tuning the size of the cache and the eviction policy, but when using the shared cache I don't see those
options, so I'm guessing that they default to the settings defined for the cached entities themselves.

See the CacheUsage class for the valid values to use with the QueryHints.CACHE_USAGE hint:

http://www.eclipse.org/eclipselink/api/2.0/org/eclipse/persistence/config/CacheUsage.html