Polaris Geometry Framework Java Developer's Guide
From BluWiki
Introduction
Design Goals
Key Concepts
Understanding The Relationship Between Geometry Definitions
Describing Location With The IPosition Interface
Storing Polaris Geometries With LocusXML
Geometry Operations
In the typical object-oriented model a class presents its behavior via a group of methods. The source code that implements these methods is stored within the source code that defines that class. Different classes that share a common interface may implement the same method in different ways internally. For instance, a Point Class and a Line Class might both implement a method called move(), that moves or translates objects of that type.
The Polaris Geometry Framework uses a slightly different approach. It groups these common methods that would be shared by geometries into a separate class known as an IGeometryOperation. An IGeometryOperation can include actions that manipulate the coordinates or shape of a Geometry, which are called Edit Operations, or actions that calculate a geometric property, which are known as Inquery Operations. (In this discussion a geometric property is an attribute or quality of a geometry that is dependent on its shape. The arc length of curve and the area of a polygon are examples of geometric properties.) What is the difference between this system, and the typical system that is described above? An example will help make this clear:
In the Polaris Geometry Framework, instead of having the Point and Line classes implement their own move() methods, you would define a new GeometryOperation object named Move. Each object implementing the IGeometryOperation object would have access to a collection of IGeometryOperationTools that provided the actual implementation of the operation to the GeometryOperation object. (You would only define a single "Move" IGeometryOperation, but you could design 2 different IGeometryOpertationTools that implement the Move operation. One for points and one for lines.)
Here is a description of the process that is initiated when client code requests a geometry operation:
[1] The client code requests a geometry operation, and provides the arguments required for the operation. (For example, a Rotation operation might require the geometry or geometries that are to be rotated, and the angle of rotation.)
[2] The arguments for the operation are wrapped into IGeometryOperationArgument objects. These are collected into a IGeometryArgumentBundle object. The bundle is in turn wrapped by a IGeometryOperationRequest object. In addition to the IGeometryArgumentBundle, the request object also provides the following:
- (1) The name of the requested operation. (For example: "Rotate")
- (2) The category of the operation. (This would be either "Edit" or "Inquiry".)
- (3) The priority of the operation. (This would be "High", "Medium", or "Low".)
[3] The IGeometryOperationRequest object is passed to the IGeometryOperationScheduler. The scheduler orders the operations for execution by their priority and time of arrival.
[4] When the IGeometryOperationExecutor signals an opening, the scheduler passes it the appropriate request. The executor creates the IGeometryOperation object in memory if it does not exist, and accesses it. The request is passed to the IGeometryOperation and the performGeometryOperation() method is called in a new thread.
[5] The IGeometryOperation object selects the correct IGeometryOperationTools based on the geometry types, other supplied arguments, and a configuration file. The build tools contain the actual code that performs the work of the operation. The results of the operation are wrapped in IGeometryOperationResult objects and collected into an IGeometryResultBundle. This bundle is wrapped into an IGeometryOperationCompletedRequest object and is passed back to the executor.
[6] The executor broadcasts an IGeometryOperationCompleted event which contains the IGeometryOperationCompletedRequest object.
What are the advantages of this system?
[1] Extendability: The main advantage of this system is extendability. This design makes it easy for developers to add new geometry types, geometry operations, and geometry operation tools to the Polaris Geometry Framework. Consider this example: A developer wants to have the ability to "twist" geometries. In a traditional system he only has a couple of choices. He can (1) add the twist() method to each geometry object defined in the framework, he can (2) create a class that wraps geometry objects and that implements the twist() method, or he can (3) build an object that accepts geometry objects and applies the twist() method internally. The first method is not desirable, becuase it requires recompilation of the source code and the developer has no way to implement the twist() method in geometries that haven't yet been added to the framework. The second method is not desirable if more than one new operation on geometries needs to be added. In that case we would get wrappers wraping wrappers wrapping wrappers..... The third method might be the best of the three presented, but could lead to a situation where each developer is designing his own set of a objects to accomplish this task. In essence, the system that will be used in the Polaris Geometry Framework is a "standardization" of this third option. It avoids needless wrapper objects, recompilation of the code, and establishes a standard way to add new geometry operations to the framework.
If, on the other hand, a developer wants to add a new geometry type to the framework, he does not have to worry about implementing methods for geometry operations that he doesn't need to support, or about having method stubs that aren't ever implemented. He simply adds the geometry operations and geometry operation tools that he wants to support his new geometry type. If another developer wants to support other operations or tools with the geometry type defined by the first developer, he can so so, with out modifying the original developers code, by adding his own geometry operation and/or geometry operation tools to the framework.
[2] Threaded: A second advantage of this system is that the execution of all geometry operations takes place in a separate thread. This may not make a noticeable difference in programs that only operate on small collections of geometry objects, but should make a significant difference in programs that work with thousands of geometry objects, as is common in GIS applications. This threaded design will also accomodate multi-user access to collections of Geometry objects. (For example, multiple users sending IGeometryOperationRequests from different OpenJUMP-Ex front-ends to a single OGD Database managed by the OpenJUMP-Ex back-end.) It is true that a new thread could be called by implementation of methods within the geometry class definitions, as in the traditional object-oriented model, but this system allows thread management to be cetnralized and managed by a single object, the IGeometryOperationExecutioner.
[3] Hooks: This sytem is designed to give developers easy access to hooks that allow them to execute code in response to the geometry operation processing. For example, each IGeometryOperation object will be based on an abstract class that broadcasts an event immediately before an operation is performed on a group of geometries. In addition, the IGeometryOperationCompletedRequest object will also be broadcast after the operation is complete. This will allow developers to design code that "listens" to and responds to the processing of geometry operations. (For example, code that refreshes a spatial index when geometries are changed, or code that verifies a user has permission to manipulate certain geometries before an operation is performed.
[4] Configurable: When the IGeometryOperationExecutor object selects the IGeometryOperationTool to use when performing an IGeometryOperation, it receives the appropriate tool from informationstored in a configuration file. This allows the user to select different implementations of a geometry operation based on the type of geometry. For example, you might want one geometry operation tool for simple line segment geometries, but another for multiline geometries.
Customizing And Extending The Framework
Custom Geometry Definitions
Custom Geometry Operations
Appendix 1: Geometry Definitions
Polaris Geometry Framework Development
