Recent commit: AngleFormat.formatToCharacterIterator and ObjectConverter

[Martin Desruisseaux <ma...@geomatys.fr>]

Hello all

In the last days, I didn't ported significant classes. Instead, I worked 
on some known holes in the existing classes, so this is new code.

The formatToCharacterIterator(Object) method defined in the 
java.text.Format class is now implemented by AngleFormat. This allows 
those who are interested in such information to known which part of the 
formatted string is the degrees field, which part is the minutes field, 
etc. It is possible to go down to "which part is the fraction digits of 
the seconds field" for example. Some Graphical User Interfaces like 
javax.swing.JFormatterTextField can use this information.

This information will cascade through SIS Format implementations. So 
when formatting a metadata object in plain text (non-XML), it will be 
possible to know for example which part is the north bound latitude 
field of a geographic bounding box (or the fraction part of the seconds 
field if someone really wants to go down to that level).

The implementation details required the port of 
org.apache.sis.util.ObjectConverter interface. I noticed that Apache 
Camel has a TypeConverter interface and Spring has a Converter 
interface. Both uses slightly different approaches, but I think that the 
Spring's one is closer to the SIS needs. The interface name is 
ObjectConverter instead than TypeConverter because it does not 
necessarily change the type; it may just changes the values while 
keeping the same type.

Compared to the Spring interface, org.apache.sis.util.ObjectConverter 
has the same "convert" method (so I think that it will be possible for 
users to implement both the Spring one and the SIS one by the same 
class), and the SIS interface defines additional methods for getting 
some information about the conversion properties. There is many ways we 
could describe the properties of such conversion, so I tried to stick to 
concept in uses in mathematics:

   * is the conversion injective?
   * is the conversion surjective?
   * is the conversion order preserving?
   * is the conversion order reversing?

The javadoc tries to explain more what "injective" or "surjective" 
means. Those information become important when we need to take in 
account the context of the objects we are converting. For example when 
converting the values of a range, if the conversing is order reversing 
then we need to swap the min and max values. If the conversion is 
neither order preserving or reversing (as for example conversions from 
Integer to String, even if String implements Comparable) then we are not 
allowed to convert range of values.

     Martin

Re: Recent commit: AngleFormat.formatToCharacterIterator and ObjectConverter

["Mattmann, Chris A (388J)" <ch...@jpl.nasa.gov>]

Thanks for the FYI here, Martin, well-needed utilities, for sure.

Cheers,
Chris

On Nov 5, 2012, at 3:29 AM, Martin Desruisseaux wrote:

> Hello all
> 
> In the last days, I didn't ported significant classes. Instead, I worked on some known holes in the existing classes, so this is new code.
> 
> The formatToCharacterIterator(Object) method defined in the java.text.Format class is now implemented by AngleFormat. This allows those who are interested in such information to known which part of the formatted string is the degrees field, which part is the minutes field, etc. It is possible to go down to "which part is the fraction digits of the seconds field" for example. Some Graphical User Interfaces like javax.swing.JFormatterTextField can use this information.
> 
> This information will cascade through SIS Format implementations. So when formatting a metadata object in plain text (non-XML), it will be possible to know for example which part is the north bound latitude field of a geographic bounding box (or the fraction part of the seconds field if someone really wants to go down to that level).
> 
> The implementation details required the port of org.apache.sis.util.ObjectConverter interface. I noticed that Apache Camel has a TypeConverter interface and Spring has a Converter interface. Both uses slightly different approaches, but I think that the Spring's one is closer to the SIS needs. The interface name is ObjectConverter instead than TypeConverter because it does not necessarily change the type; it may just changes the values while keeping the same type.
> 
> Compared to the Spring interface, org.apache.sis.util.ObjectConverter has the same "convert" method (so I think that it will be possible for users to implement both the Spring one and the SIS one by the same class), and the SIS interface defines additional methods for getting some information about the conversion properties. There is many ways we could describe the properties of such conversion, so I tried to stick to concept in uses in mathematics:
> 
>  * is the conversion injective?
>  * is the conversion surjective?
>  * is the conversion order preserving?
>  * is the conversion order reversing?
> 
> The javadoc tries to explain more what "injective" or "surjective" means. Those information become important when we need to take in account the context of the objects we are converting. For example when converting the values of a range, if the conversing is order reversing then we need to swap the min and max values. If the conversion is neither order preserving or reversing (as for example conversions from Integer to String, even if String implements Comparable) then we are not allowed to convert range of values.
> 
>    Martin
>