Details
Improvement
Closed
Description
We need to improve the documentation of GenericName. A first draft has already been created in the form of a table added in class javadoc for illustration purpose:
http://geoapi.sourceforge.net/snapshot/javadoc/org/opengis/util/GenericName.html
http://geoapi.sourceforge.net/snapshot/javadoc/org/opengis/util/ScopedName.html
Examples were added in most methods. In addition, we need to apply the following renaming:
- GenericName.name() to tip()
Usage of name() is confusing since it applies to the whole entity represented by a GenericName while this method was only for the last element in the list of parsed names.
We should also promote ScopedName.head() to GenericName for consistency with tip() and for documentation purpose since it is mentioned in the GenericName class javadoc. This promotion would not hurt since this method can have a well specified behavior for LocalName as well as ScopedName.
Issue Links
| This issue is related to: | ||||
| GEO-144 | Add Name.getSeparator() to simplify use of Name interface |
|
|
|
For me the GenericName API is confusing on two fronts; its intended use in an ISO specification seems more along the lines of "reflection" than "identification". You can see this in many constructs (like RecordType) extending GenericName in order to locate them selves in a naming service. This is counter to the Java practices of locating objects in a Map<URI,Object>; or in more formal projects in a JNDI naming service.
You will find JNDI is built on some of the same ideas as GenericName - they just don't have that strange custom of making the "named thing" extend GenericName.
One idea:
We do need to make sure the difference in goals is clear - java programs are going to usually assume "identification" as the roal of a Name.
- reduce the number of methods in GenericName to the point it is an interface people can "mix in" to their existing classes
- the idea of a GenericName needing its Namespace in order to be valid is troublesome; if we can offload a lot of the functionality onto the NameSpace implementation and have a NameSpace.add( LocalName ) that ensure the correct details are filled in we would be in a good position to let implementors successfully "register" their content in the GenericName / LocalName tree data structure.
We do need to make sure the difference in goals is clear - java programs are going to usually assume "identification" as the roal of a Name.