Purpose of this Document This document describes the various strategies and trade offs you should consider when making Java interfaces from a specification.

GeoAPI produces interfaces from various specifications. When looking at an specification for the first time you need to determine how you plan for it to be used, please pay careful attention to issues of mutability and thread safety.

Creating Interfaces from a Specification

The following pages contain the details on converting a specification into geoapi packages and interfaces.

• Specification Name and Description — The specification name and description will be used to figure out your java package and package-info.java.
• UML Diagram — The vast benefit of these specifications is communicated via their included UML diagrams. We use this information to define the names of our interfaces, methods and fields.
• Data Definition — The data definition in a specification are usually provided as a "Data Dictionary" or "XML Schema". This information is where we find details for our javadocs.

Interface Design

If you thought the preceding section was too easy you are correct - it is. If you follow the directions above you will be left with a perfect read-only interface that can safely be used for communication between modules, across threads, and even systems. If you want to do more please read this section on interface design, there are still some choices to be made.

• Publication — READ-ONLY
• Factory — create and read-only
• Visit — create, read-only, and visiting - giving us transformations
• Unsafe — READ-WRITE on the HONOUR SYSTEM
• Data Object — READ_WRITE with EQUALS
• Mutable — READ-WRITE with SYNCHRONIZATION and EVENTS

BEFORE YOU START

When looking at an interface we need to pay attention to a couple of things:

Q: This page is too long - what do I need to do?

If you don't have time to think:

• Make the interface read-only

Doing this will take away all the hard questions about thread safety and mutability.

Q: When should I make an interface read-only?

Is the information intended for publication or description?

• If so perhaps you can make the interface immutable

Is the interface used across threads?

• If so you really should make the interface immutable

Q: When should I supply a Factory?

Would an application need to supply a specific implementation?

• If so you will need to provided a Factory

Q: When should I make a data object?

Would you like to edit information and then copy it for another thread (or machine)?

• You will need to specify your interface as a DataObject (with equals and hashcode)

Q: When should I define event notification?

Are you planning to edit information in an environment with multiple threads?

• If so you will need to provide event notification
• Please make it clear to implementors that synchronization and/or internal locks will be required
• The JavaBeans specification has lots of advice (and utility classes) for doing this kind of work