This page represents the current plan; for discussion please check the tracker link above.

Description

Currently, GeoTools is tuned for use by a very small number of concurrent users. When deploying this subsystem in a highly threaded environment with thousands of users some shortcomings are revealed:

• Allowing Multiple Users - currently multiple threads are only supported by virtue of being serviced by a cache hit, only one thread is allowed to work on a cache hit at a time.
• Cache Handling - we need to ensure the two caching techniques used (pool and findPool) are able to function in the face of multiple threads (both reading and writing).
• Connection Issues - this is a related issue only of interest to CRSAuthority implementation making use of an EPSG Database, we need to ensure that supporting multiple threads does not result in Connections being leaked from the java.sql.DataSource provided.

Status

This proposal has been accepted; implemented and is waiting the attentions of the Module Maintainer for referencing. We are currently running two implementations of the various base classes.

{dynamictasklist:Impediments}{dynamictasklist}

Resources

Tasks

2.4-M4:

1. Jody Garnett Rename CRSAuthortyFactory classes for clarity
2. Cory Horner Isolate ObjectCache
3. Martin Desruisseaux Review ObjectCache API
4. Jody Garnett Review and document ObjectCache
5. Cory Horner Create DefaultObject Cache and stress test
6. Jody Garnett Break BufferedAuthorityFactory into three parts; one for each responsibility

2.4-RC0:

1. Jody Garnett Create WeakObject and FixedObjectCache for stress testing
2. Cory Horner AbstractCachedAuthorityFactory - inject ObjectCache into worker
3. Cory Horner AbstractCachedAuthorityMediator - provide Hints to control Object Pool
4. Jody Garnett Set up OracleDialectEpsgFactory lifecycle for Connection use
5. Jody Garnett Using HsqlDialectEpsgMediator - confirm ObjectPool can manage a single worker
6. Jody Garnett Finish renaming the EpsgFactory classes for clarity
7. Martin Desruisseaux Review and update Naming in response to Implementation
8. Cory Horner Provided a test to Break ObjectCache memory limit
9. Cory Horner Use WeakReferences to keep withing memory limit

2.4-RC1:

1. Martin Desruisseaux Review HSQL implementation and deprecate old approach
2. Jody Garnett Complete documentation
3. Jody Garnett Stress test epsg-oracle module
4. Jody Garnett Bring oracle-epsg up to supported status |

API Changes

Public API change

This results in no change to client code - all client code should be making use of one of AuthorityFactory sub-interfaces or the CRS facade as documented here:

• 01 CRS Helper Class

Internal API change

So what is this change about then? This change request is for the internals of the referencing module, and the relationship between the super classes defined therein and the plug in modules providing implementations.

Requests:

• Stop calling everything Factory
• Try and communicate the difference between an authority "using oracle to host the EPSG database" and "using the Oracle SRID wkt definition"
• Keep in mind that most authority factories are about CoordinateReferenceSystem, CoordinateSystem, Datum, CoordinateOperation, etc.
• Sort order of the names matter for people reading javadocs - they should be able to see alternatives sorted together
  • (note from Martin: I agree about grouping the related alternatives, but I don't think that we should do that through alphabetical order if it produces confusing names. Grouping is Javadoc's job. Current javadoc tool can do that at the packages level. Future javadoc tool will be able to do that at the classes and methods level. So lets not produce bad names for working around a temporary javadoc limitation)
• Please don't hold up your vote over naming - if you see something you want edit the page and vote +1

Design Changes

We are documenting this as a refactoring with BEFORE and AFTER pictures. For design alternatives please review the comments of GEOT-1286

BEFORE

For background reading on the design of the GeoTools referencing system:

• 0 Referencing Overview
• 3 Authorities backed by the EPSG Database

Allowing Multiple Users

FactoryOnOracle (ie a BufferedAuthorityFactory) allows multiple threads, making use of a an internal pool as a cache for objects already constructed. In the event of a cache miss the backingStore is used to create the required object.

FactoryUsingOracleSQL (ie a DirectAuthorityFactory acting as a "backingStore") has synchronized each and every public method call (internally it makes use of a Thread lock check to ensure that subclasses do not confuse matters).

When creating compound objects will make a recursive call to its parent buffered FactoryOnOracle. This recursive relationship is captured in the sequence diagram above.

A Timer is used to dispose of the backingStore when no longer in use.

Cache Handling

FactoryOnOracle (ie a BufferedAuthorityFactory) makes use a pool (a HashMap of strong and weak references) in order to track referencing objects created for use by client code. By default, the 20 most recently used objects are hold by strong references, and the remainding ones are hold by weak references. A second cache, findPool, makes use of a HashMap of WeakReferences in order to keep temporary referencing objects created during the use of the find method.

The garbage collector is used to clean out weak references as needed.

Connection Issues

A single connection is opened by FactoryOnOracle, and handed over to the backingStore (ie FactoryUsingSQL) on construction. This connection is closed after a 20 mins idle perriod (at which point the entire backingStore is shut down). This work is performed by a timer task in DeferredAuthorityFactory, not to be confused with the thread shutdown in DefaultFactory, which is a shutdown hook used to ensure the connection is closed at JVM shutdown time.

AFTER

The referencing module functions as normal, classes have been renamed according to function:

Allowing Multiple Users

EPSGOracleThreadedAuthority allows multiple threads, making use of ReferencingObjectCache in order to return objects previously constructed and an ObjectPool of workers to create new content in the event of a cache miss.

To build compound objects the workers will need to share the cache with the parent.

The following sequence diagram shows the behaviour of EPSGOracleThreadedAuthority when responding to a createDatum request. Initially the requested datum is not in the cache, a worker is retrieved from the ObjectPool and used to perform the work. Of interest is the use of the shared ReferencingObjectCache to block subsequent workers from duplicating this activity.

Cache Handling

The cache has been isolated into a single class - ReferencingObjectCache. This class is responsible for storing strong references to objects already created and released to code outside of the referencing module.

The ReferencingObjectCache stores an internal Map<Obj,Reference> as described in the following table.

• During a Cache Hit: The entry is looked up in the internal map, if the value is found it is returned. If a soft reference is found the value is extracted if needed (the soft reference may be changed into a strong reference if needed).
• During a Cache Miss: A worker is produced to construct the appropriate object; the worker will reserve the spot in the cache with a placeholder reference, produce the required object and place it into the cache. The placeholder will then be removed and all threads waiting for the value released.
• During a Cache Conflict: More than one worker is released to construct the appropriate object; the first worker will reserve using a placeholder object - and the second will block. When the placeholder is released the second worker will consider itself as having undergone a cache hit and behave as normal.

As noted above the ReferencingObjectCache class is thread safe.

Connection Issues

EPSGOracleThreadedAuthority is the keeper of a DataSource which is provided to EPSGOracleDirectAuthority workers on construction. The EPSGOracleDirectAuthority workers use their dataSource to create a connection as needed, they will also keep a cache of PreparedStatements opened against that connection.

The ObjectPool lifecycle methods are implemented allowing EPSGOracleDirectAuthority object to be notified when no longer in active use. At this point their PreparedStatements and Connection can be closed - and reclaimed by the DataSource

We will need to make use of a single worker (and use it to satisfy multiple definitions) when implementing the find method.

By providing hints to tune the ObjectPool we can allow an application to:

• Ensure that less workers are in play than number of Connections managed by the DataSource (so other oracle modules do not starve)
• Emulate the current 20 min timeout behavior
• Arrive at a compromise for J2EE applications (where a worker can free it's connection the moment it is no longer in constant use)

Documentation Changes

Update Module matrix pages

• Referencing Module
• EPSG-Oracle Plugin

Update User Guide:

• ObjectCache - done
• Update Referencing Developers Guide
  • 0 Referencing Overview
  • 2 Referencing Factories
  • 3 Authorities backed by the EPSG Database

Issue Tracker:

• check related issues to see of problems are affected