Copied: sis/site/trunk/book/en/utility/ObjectConverters.html (from r1794573, sis/site/trunk/book/en/utility.html) URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/utility/ObjectConverters.html?p2=sis/site/trunk/book/en/utility/ObjectConverters.html&p1=sis/site/trunk/book/en/utility.html&r1=1794573&r2=1794656&rev=1794656&view=diff ============================================================================== --- sis/site/trunk/book/en/utility.html [UTF-8] (original) +++ sis/site/trunk/book/en/utility/ObjectConverters.html [UTF-8] Tue May 9 23:04:35 2017 @@ -22,99 +22,20 @@ - Utility classes and methods + ObjectConverters - +
-

Utility classes and methods

+

Object converters

- This chapter describes aspects of Apache SIS that apply to the entire library. - Most of these utilities are not specific to spatial information systems. -

- -

Comparison modes of objects

-

- There are various opinions on how to implement Java standard’s Object.equals(Object) method. - According to some, it should be possible to compare different implementations of the same interface or base class. - But to follow this policy, each interface or base class’s javadoc must define the algorithms that all implementations - shall use for their equals(Object) and hashCode() methods. - This approach is common in java.util.Collection and its child interfaces. - Transferring this approach to certain GeoAPI interfaces, however, would be a difficult task, - and would probably not be followed in many implementations. - Moreover, it comes at the expense of being able to take into account supplementary attributes in the child interfaces, - unless this possibility has been specified in the parent interface. - This constraint arises from the following points of the equals(Object) and hashCode() method contracts: -

- -

- For example, these three constraints are violated if A (and eventually C) can contain attributes - which B ignores. - To bypass this problem, an alternative approach is to require that the objects compared by the - Object.equals(Object) method be of the same class; in other words, A.getClass() == B.getClass(). - This approach is sometimes regarded as contrary to the principles of object oriented programming. - In practice, for relatively complex applications, the important accorded to these principles depends on the context - in which the objects are compared: - if the objects are added to a HashSet or used as keys in a HashMap, - we would need a stricter adherence to the equals(Object) and hashCode() contract. - But if the developer is comparing the objects his- or herself, for example to check that the relevant information has been changed, - then the constraints of symmetry, transitivity or coherence with the hash values may be of little interest. - More permissive comparisons may be desirable, sometimes going so far as to tolerate minor discrepancies in numerical values. -

-

- In order to allow developers a certain amount of flexibility, many classes in the SIS - library implement the org.apache.sis.util.LenientComparable interface, - which defines a equals(Object, ComparisonMode) method. - The principle modes of comparison are: -

- -

- The default mode, used in all equals(Object) methods in SIS, - is STRICT. This mode is chosen for a safe operation — particularly with HashMap — - without the need to rigorously define equals(Object) and hashCode() operations in every interface. - With this mode, the order of objects (A.equals(B) or B.equals(A)) is unimportant. - It is, however, the only mode that offers this guarantee. - In the expression A.equals(B), the BY_CONTRACT mode - (and so by extension all other modes that depend on it) only compares the properties known to A, - regardless of whether B knows more. -

- - - -

Object converters

-

There is sometime a need to convert instances from a source Java type to a target Java type while those types are unknown at compile time. Various projects (Apache Common Convert, Spring, etc.) @@ -192,200 +113,6 @@ If the converter is neither order preserving or order reversing, then range conversion is not allowed at all (because it does not contain the same set of values) even if the minimum and maximum values could be converted individually.

- - - -

Internationalization

-

- In an architecture where a program executed on a server provides its data to multiple clients, - the server’s locale conventions are not necessarily the same as those of the clients. - Conventions may differ in language, but also in the way they write numeric values - (even between two countries that speak the same language) as well in time zone. - To produce messages that conform to the client’s conventions, SIS uses - two approaches, distinguished by their level of granularity: at the level of the messages themselves, - or at the level of the objects that create the messages. - The approach used also determines whether it is possible to share the same instance of an object for all languages. -

- -

Distinct character sequences for each locale

-

- Some classes are only designed to function according to one locale convention at a time. - This is of course true for the standard implementations of java.text.Format, - as they are entirely dedicated to the work of internationalization. - But it is also the case for other less obvious classes like javax.imageio.ImageReader and ImageWriter. - When one of these classes is implemented by SIS, - we identify it by implementing the org.apache.sis.util.Localized interface. - The getLocale() method of this interface can determine the locale conventions - by which the instance produces its message. -

-

- Another class that provides different methods for different locales is java.lang.Throwable. - The standard Java API defines two methods for getting the error message: - getMessage() and getLocalizedMessage(). - Usually those two methods return the same character sequences, - but some exceptions thrown by Apache SIS may use different locales. - The policy that SIS tries to apply on a best-effort basis is: -

- - -

Example: - If an error occurred while a Japanese client connected to an European server, the localized message may be sent - to the client in Japanese language as given by getLocalizedMessage() while the same error may be - logged on the server side in the French (for example) language as given by getMessage(). - This allows system administrator to analyze the issue without the need to understand client’s language. -

-

- The utility class org.apache.sis.util.Exceptions provides convenience methods to get messages - according to the conventions of a given locale, when this information is available. -

- - - -

Single instance for all supported locales

-

- The API conventions defined by SIS or inherited by GeoAPI favour the use of the - InternationalString type when the value of a String type would likely be localized. - This approach allows us to defer the internationalization process to the time when a character sequence is requested, - rather than the time when the object that contains them is created. - This is particularly useful for immutable classes used for creating unique instances independently of locale conventions. -

-

Example: - SIS includes only one instance of the OperationMethod - type representing the Mercator projection, regardless of the client’s language. - But its getName() method (indirectly) provides an instance of - InternationalString, so that toString(Locale.ENGLISH) returns Mercator projection - while toString(Locale.FRENCH) returns Projection de Mercator. -

-

- When defining spatial objects independently of locale conventions, we reduce the risk of computational overload. - For example, it is easier to detect that two maps use the same cartographic projection if this last is represented by the - same instance of CoordinateOperation, - even if the projection has a different name depending on the country. - Moreover, certain types of CoordinateOperation may require coordinate transformation matrices, - so sharing a single instance becomes even more preferable in order to reduce memory consumption. -

- - - -

Locale.ROOT convention

-

- All SIS methods receiving or returning the value of a Locale type accept the Locale.ROOT value. - This value is interpreted as specifying not to localize the text. - The notion of a non-localized text is a little false, as it is always necessary to chose a formatting convention. - This convention however, though very close to English, is usually slightly different. - For example: -

- - - - -

Treatment of characters

-

- In Java, sequences of characters use UTF-16 encoding. - There is a direct correspondence between the values of the char type and the great majority of characters, - which facilitates the use of sequences so long as these characters are sufficient. - However, certain Unicode characters cannot be represented by a single char. - These supplementary characters include certain ideograms, - but also road and geographical symbols in the 1F680 to 1F700 range. - Support for these supplementary characters requires slightly more complex interactions than the classic case, - where we may assume a direct correspondence. - Thus, instead of the loop on the left below, international applications must generally use the loop on the right: -

- - - - - - - - - - - - -

- SIS supports supplementary characters by using the loop on the right where necessary, - but the loop on the left is occasionally used when it is known that the characters searched for are not supplementary characters, - even if some may be present in the sequence in which we are searching. -

- - - -

Blank spaces interpretation

-

- Standard Java provides two methods for determining whether a character is a blank space: - Character.isWhitespace(…) and Character.isSpaceChar(…). - These two methods differ in their interpretations of non-breaking spaces, tabs and line breaks. - The first method conforms to the interpretation currently used in languages such as Java, C/C++ and XML, - which considers tabs and line breaks to be blank spaces, while non-breaking spaces are read as not blank. - The second method — which conforms strictly to the Unicode definition — makes the opposite interpretation. -

-

- SIS uses each of these methods in different contexts. - isWhitespace(…) is used to separate the elements of a list (numbers, dates, words, etc.), - while isSpaceChar(…) is used to ignore blank spaces inside a single element. -

-

Example: - Take a list of numbers represented according to French conventions. - Each number may contain non-breaking spaces as thousands separators, - while the different numbers in the list may be separated by ordinary spaces, tabs or line breaks. - When analyzing a number, we want to consider the non-breaking spaces as being part of the number, - whereas a tab or a line break most likely indicates a separation between this number and the next. - We would thus use isSpaceChar(…). - Conversely, when separating the numbers in the list, we want to consider tabs and line breaks as separators, - but not non-breaking spaces. - We would thus use isWhitespace(…). - The role of ordinary spaces, to which either case might apply, should be decided beforehand. -

-

- In practice, this distinction is reflected in the use of isSpaceChar(…) in the implementations of java.text.Format, - or the use of isWhitespace(…) in nearly all the rest of the SIS library. -

Copied: sis/site/trunk/book/en/utility/Utilities.html (from r1794573, sis/site/trunk/book/en/utility.html) URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/utility/Utilities.html?p2=sis/site/trunk/book/en/utility/Utilities.html&p1=sis/site/trunk/book/en/utility.html&r1=1794573&r2=1794656&rev=1794656&view=diff ============================================================================== --- sis/site/trunk/book/en/utility.html [UTF-8] (original) +++ sis/site/trunk/book/en/utility/Utilities.html [UTF-8] Tue May 9 23:04:35 2017 @@ -20,15 +20,15 @@ under the License. --> - + - Utility classes and methods + Utilities - +
@@ -40,352 +40,9 @@ Most of these utilities are not specific to spatial information systems.

-

Comparison modes of objects

-

- There are various opinions on how to implement Java standard’s Object.equals(Object) method. - According to some, it should be possible to compare different implementations of the same interface or base class. - But to follow this policy, each interface or base class’s javadoc must define the algorithms that all implementations - shall use for their equals(Object) and hashCode() methods. - This approach is common in java.util.Collection and its child interfaces. - Transferring this approach to certain GeoAPI interfaces, however, would be a difficult task, - and would probably not be followed in many implementations. - Moreover, it comes at the expense of being able to take into account supplementary attributes in the child interfaces, - unless this possibility has been specified in the parent interface. - This constraint arises from the following points of the equals(Object) and hashCode() method contracts: -

- -

- For example, these three constraints are violated if A (and eventually C) can contain attributes - which B ignores. - To bypass this problem, an alternative approach is to require that the objects compared by the - Object.equals(Object) method be of the same class; in other words, A.getClass() == B.getClass(). - This approach is sometimes regarded as contrary to the principles of object oriented programming. - In practice, for relatively complex applications, the important accorded to these principles depends on the context - in which the objects are compared: - if the objects are added to a HashSet or used as keys in a HashMap, - we would need a stricter adherence to the equals(Object) and hashCode() contract. - But if the developer is comparing the objects his- or herself, for example to check that the relevant information has been changed, - then the constraints of symmetry, transitivity or coherence with the hash values may be of little interest. - More permissive comparisons may be desirable, sometimes going so far as to tolerate minor discrepancies in numerical values. -

-

- In order to allow developers a certain amount of flexibility, many classes in the SIS - library implement the org.apache.sis.util.LenientComparable interface, - which defines a equals(Object, ComparisonMode) method. - The principle modes of comparison are: -

- -

- The default mode, used in all equals(Object) methods in SIS, - is STRICT. This mode is chosen for a safe operation — particularly with HashMap — - without the need to rigorously define equals(Object) and hashCode() operations in every interface. - With this mode, the order of objects (A.equals(B) or B.equals(A)) is unimportant. - It is, however, the only mode that offers this guarantee. - In the expression A.equals(B), the BY_CONTRACT mode - (and so by extension all other modes that depend on it) only compares the properties known to A, - regardless of whether B knows more. -

- - - -

Object converters

-

- There is sometime a need to convert instances from a source Java type to a target Java type - while those types are unknown at compile time. - Various projects (Apache Common Convert, Spring, etc.) - have created their own interface for performing object conversions between types known only at runtime. - Details vary, but such interfaces typically look like below: -

- -
interface ObjectConverter<S,T> {   // Some projects use only "Converter" as interface name.
-    T apply(S object);             // Another method name commonly found in other projects is "convert".
-}
- -

- Like other projects, Apache SIS also defines its own ObjectConverter interface. - The main difference between SIS converter interface and the interfaces found in other projects - is that SIS converters provide some information about their mathematical properties. - An Apache SIS converter can have zero, one or many of the following properties: -

-
-
Injective
-
A function is injective if no pair of S values can produce the same T value. -

Example: - the IntegerString conversion performed by Integer.toString() - is an injective function because if two Integer values are not equal, - then it is guaranteed that their conversions will result in different String values. - However the StringInteger conversion performed by Integer.valueOf(String) - is not an injective function - because many distinct String values can be converted to the same Integer value. - For example converting the "42", "+42" and "0042" character strings all result in the same 42 integer value. -

-
- -
Surjective
-
A function is surjective if each values of T can be created from at least one value of S. -

Example: - the StringInteger conversion performed by Integer.valueOf(String) - is a surjective function because every Integer value can be created from at least one String value. - However the IntegerString conversion performed by Integer.toString() - is not a surjective function because it can not produce all possible String values. - For example there is no way to produce the "ABC" value with the Integer.toString() method. -

-
- -
Bijective
-
A function is bijective if there is a one-to-one relationship between S and T values. -

Note: - the bijective property is defined here for clarity, but actually does not have an explicit item - in Apache SIS FunctionProperty enumeration. - It is not necessary since a function that is both injective and surjective is necessarily bijective. -

-
- -
Order preserving
-
A function is order preserving if any sequence of increasing S values is mapped to a sequence of increasing T values. -

Example: - conversion from Integer to Long preserve the natural ordering of elements. - However conversions from Integer to String do not preserve natural ordering, - because some sequences of increasing integer values are ordered differently when their string representations are sorted by lexicographic order. - For example 1, 2, 10 become "1", "10", "2". -

-
- -
Order reversing
-
A function is order reversing if any sequence of increasing S values is mapped to a sequence of decreasing T values. -

Example: - a conversion that reverses the sign of numbers. -

-
-
-

- Above information may seem unnecessary when values are converted without taking in account the context in which the values appear. - But when the value to convert is part of a bigger object, then above information can affect the way the converted value will be used. - For example conversion of a [minmax] range is straightforward when the converter is order preserving. - But if the converter is order reversing, then the minimum and maximum values need to be interchanged. - For example if the converter reverses the sign of values, then the converted range is [-max … -min]. - If the converter is neither order preserving or order reversing, then range conversion is not allowed at all - (because it does not contain the same set of values) even if the minimum and maximum values could be converted individually. -

- - - -

Internationalization

-

- In an architecture where a program executed on a server provides its data to multiple clients, - the server’s locale conventions are not necessarily the same as those of the clients. - Conventions may differ in language, but also in the way they write numeric values - (even between two countries that speak the same language) as well in time zone. - To produce messages that conform to the client’s conventions, SIS uses - two approaches, distinguished by their level of granularity: at the level of the messages themselves, - or at the level of the objects that create the messages. - The approach used also determines whether it is possible to share the same instance of an object for all languages. -

- -

Distinct character sequences for each locale

-

- Some classes are only designed to function according to one locale convention at a time. - This is of course true for the standard implementations of java.text.Format, - as they are entirely dedicated to the work of internationalization. - But it is also the case for other less obvious classes like javax.imageio.ImageReader and ImageWriter. - When one of these classes is implemented by SIS, - we identify it by implementing the org.apache.sis.util.Localized interface. - The getLocale() method of this interface can determine the locale conventions - by which the instance produces its message. -

-

- Another class that provides different methods for different locales is java.lang.Throwable. - The standard Java API defines two methods for getting the error message: - getMessage() and getLocalizedMessage(). - Usually those two methods return the same character sequences, - but some exceptions thrown by Apache SIS may use different locales. - The policy that SIS tries to apply on a best-effort basis is: -

- - -

Example: - If an error occurred while a Japanese client connected to an European server, the localized message may be sent - to the client in Japanese language as given by getLocalizedMessage() while the same error may be - logged on the server side in the French (for example) language as given by getMessage(). - This allows system administrator to analyze the issue without the need to understand client’s language. -

-

- The utility class org.apache.sis.util.Exceptions provides convenience methods to get messages - according to the conventions of a given locale, when this information is available. -

- - - -

Single instance for all supported locales

-

- The API conventions defined by SIS or inherited by GeoAPI favour the use of the - InternationalString type when the value of a String type would likely be localized. - This approach allows us to defer the internationalization process to the time when a character sequence is requested, - rather than the time when the object that contains them is created. - This is particularly useful for immutable classes used for creating unique instances independently of locale conventions. -

-

Example: - SIS includes only one instance of the OperationMethod - type representing the Mercator projection, regardless of the client’s language. - But its getName() method (indirectly) provides an instance of - InternationalString, so that toString(Locale.ENGLISH) returns Mercator projection - while toString(Locale.FRENCH) returns Projection de Mercator. -

-

- When defining spatial objects independently of locale conventions, we reduce the risk of computational overload. - For example, it is easier to detect that two maps use the same cartographic projection if this last is represented by the - same instance of CoordinateOperation, - even if the projection has a different name depending on the country. - Moreover, certain types of CoordinateOperation may require coordinate transformation matrices, - so sharing a single instance becomes even more preferable in order to reduce memory consumption. -

- - - -

Locale.ROOT convention

-

- All SIS methods receiving or returning the value of a Locale type accept the Locale.ROOT value. - This value is interpreted as specifying not to localize the text. - The notion of a non-localized text is a little false, as it is always necessary to chose a formatting convention. - This convention however, though very close to English, is usually slightly different. - For example: -

- - - - -

Treatment of characters

-

- In Java, sequences of characters use UTF-16 encoding. - There is a direct correspondence between the values of the char type and the great majority of characters, - which facilitates the use of sequences so long as these characters are sufficient. - However, certain Unicode characters cannot be represented by a single char. - These supplementary characters include certain ideograms, - but also road and geographical symbols in the 1F680 to 1F700 range. - Support for these supplementary characters requires slightly more complex interactions than the classic case, - where we may assume a direct correspondence. - Thus, instead of the loop on the left below, international applications must generally use the loop on the right: -

- - - - - - - - - - - - -

- SIS supports supplementary characters by using the loop on the right where necessary, - but the loop on the left is occasionally used when it is known that the characters searched for are not supplementary characters, - even if some may be present in the sequence in which we are searching. -

- - - -

Blank spaces interpretation

-

- Standard Java provides two methods for determining whether a character is a blank space: - Character.isWhitespace(…) and Character.isSpaceChar(…). - These two methods differ in their interpretations of non-breaking spaces, tabs and line breaks. - The first method conforms to the interpretation currently used in languages such as Java, C/C++ and XML, - which considers tabs and line breaks to be blank spaces, while non-breaking spaces are read as not blank. - The second method — which conforms strictly to the Unicode definition — makes the opposite interpretation. -

-

- SIS uses each of these methods in different contexts. - isWhitespace(…) is used to separate the elements of a list (numbers, dates, words, etc.), - while isSpaceChar(…) is used to ignore blank spaces inside a single element. -

-

Example: - Take a list of numbers represented according to French conventions. - Each number may contain non-breaking spaces as thousands separators, - while the different numbers in the list may be separated by ordinary spaces, tabs or line breaks. - When analyzing a number, we want to consider the non-breaking spaces as being part of the number, - whereas a tab or a line break most likely indicates a separation between this number and the next. - We would thus use isSpaceChar(…). - Conversely, when separating the numbers in the list, we want to consider tabs and line breaks as separators, - but not non-breaking spaces. - We would thus use isWhitespace(…). - The role of ordinary spaces, to which either case might apply, should be decided beforehand. -

-

- In practice, this distinction is reflected in the use of isSpaceChar(…) in the implementations of java.text.Format, - or the use of isWhitespace(…) in nearly all the rest of the SIS library. -

+ + +
Copied: sis/site/trunk/book/en/xml/XML-ISO-19115.html (from r1794655, sis/site/trunk/book/en/xml.html) URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/xml/XML-ISO-19115.html?p2=sis/site/trunk/book/en/xml/XML-ISO-19115.html&p1=sis/site/trunk/book/en/xml.html&r1=1794655&r2=1794656&rev=1794656&view=diff ============================================================================== --- sis/site/trunk/book/en/xml.html [UTF-8] (original) +++ sis/site/trunk/book/en/xml/XML-ISO-19115.html [UTF-8] Tue May 9 23:04:35 2017 @@ -22,111 +22,20 @@ - Representing objects in XML + XML-ISO-19115 - +
-

Representing objects in XML

+

Representing metadata according to ISO 19115-3

- Objects defined by OGC/ISO standards must be able to communicate with remote machines via the Internet, - using different software written in different languages. - Some of the better known formats include WKT (Well-Known Text) and WKB (Well-Known Binary). - But the most exhaustive and often referred format is XML, - to the point where the representation of ISO objects in this format is itself sometimes - the entire focus of an international standard. - Thus are metadata classes described in ISO 19115-1 standard (an abstract specification), - while the representation of these classes in XML is described in ISO 19115-3 and 19139 standards. -

-

- Different OGC/ISO standards do not always use the same strategy to express objects in XML. - ISO 19115-3 standard in particular uses a more verbose approach than other standards, - and will be the subject of its own section. - But most XML formats define supplementary types and attributes that are not part of the original abstract specifications. - These supplementary attributes are usually specific to XML and may not appear in the API of Apache SIS. - However, some of these attributes, such as id, uuid and - xlink:href, remain accessible in the form of key-value pairs. -

-

- XML documents may use any prefixes, - but the following prefixes are commonly used. - They therefore appear by default in documents produced by Apache SIS. - These prefixes are defined in the org.apache.sis.xml.Namespaces class. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Common XML namespace prefixes
PrefixNamespace
gcohttp://www.isotc211.org/2005/gco
gfchttp://www.isotc211.org/2005/gfc
gmdhttp://www.isotc211.org/2005/gmd
gmihttp://www.isotc211.org/2005/gmi
gmxhttp://www.isotc211.org/2005/gmx
gmlhttp://www.opengis.net/gml/3.2
xlinkhttp://www.w3.org/1999/xlink
- - - - - -

Representing metadata according to ISO 19115-3

-

For each metadata class, there is an XML type with the same name than in the abstract specification (for example, gmd:MD_Metadata and gmd:CI_Citation). All of these types may be used as the root of an XML document. @@ -205,7 +114,7 @@ These classes may be ignored, unless the developer wishes to implement his or her own classes whose instances must be written in JAXB.

-