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.

Resources

Tasks

	no progress		done		impeded		lack mandate/funds/time		volunteer needed

2.4-M4:

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

2.4-RC0:

1. jgarnett 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. jgarnett Set up OracleDialectEpsgFactory lifecycle for Connection use
5. jgarnett Using HsqlDialectEpsgMediator - confirm ObjectPool can manage a single worker
6. jgarnett 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. jgarnett Complete documentation
3. jgarnett Stress test epsg-oracle module
4. jgarnett 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

BEFORE	Proposed	AFTER	Role and Responsibility
			Class diagrams, additional diagrams follow.
AbstractFactory	unchanged	unchanged
ReferencingFactory	unchanged	unchanged
AbstractAuthorityFactory	AbstractAuthority	AbstractAuthorityFactory	Authority providing the definition of referencing objects for a code
BEFORE	Proposed	AFTER	Role and Responsibility
BufferedAuthorityFactory	ThreadedAuthority	AbstractAuthorityMediator	Manages a shared cache and worker creation/dispatch/reuse for multiple threads
		CachedAuthorityDecorator	Decorator used to wrap cache support around an existing authority
		AbstractCachedAuthorityFactory	Acts as a super class for authority factories making use of a cache
	DefaultReferencingObjectCache	DefaultReferencingObjectCache	Shared cache implementation
	ObjectPool	ObjectPool	An off the shelf component from commons-pool
DeferredAuthorityFactory			remove
DefaultFactory	EPSGThreadedAuthority	EpsgMediator	Implementation backed by official EPSG database
FactoryOnOracleSQL	EPSGOracleThreadedAuthority	OracleEpsgMediator	When the EPSG database is loaded into Oracle
BEFORE	Proposed	AFTER	Role and Responsibility
DirectAuthorityFactory	DirectAuthority	AbstractCachedAuthorityFactory	Direct access to an authority
	NullReferencingObjectCache	NullObjectCache	NullObject used to maintain stand-alone functionality
FactoryUsingSQL	EPSGDirectAuthority	EpsgFactory	Consult an offical EPSG database for CRS definition
		AccessDialectEpsgFactory	Dialect for Access SQL
FactoryUsingAnsiSQL	EPSGAnsiDirectAuthority	AnsiDialectEpsgFactory	Dialect for ANSI SQL
FactoryUsingOracleSQL	EPSGOracleDirectAuthority	OracleDialectEpsgFactory	Dialect for Oracle SQL
BEFORE	Proposed	AFTER	Role and Responsibility
FactoryGroup	ReferencingFactoryContainer	ReferencingFactoryContainer	Holds all the factories needed to create stuff.
GeotoolsFactory	ReferencingObjectFactory	ReferencingObjectFactory	Creates the default implementations provided by the GeoTool library
WeakHashSet	WeakHashSet	WeakHashSet	Uses weak references to store set contents
	CanonicalSet	CanonicalSet	Isolate toUnique method in order to implement "intern" functionality

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

Runtime Overview	Class Diagram	Sequence Diagram

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:

Runtime Overview

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.

Class Diagram

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.

Sequence Diagram

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.

Sequence Diagram

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