Package names

Up to version 1.5.x, jrawio does not contain any public API, as it is just a service provider for Image I/O. This means that package, class and method names can change from version to version without any long-term warning. This situation is going to change in future:

1. Because of enhancements in version 1.6 and 3.0
2. Because of the use of Metadata classes

Both aspects call for a stabilisation of the API. While in the former case the naming schemata are being defined by the related version specifications, metadata is a special case. Basically, Image I/O mandates that metadata can be accessed by using the standard Java APIs and getting metadata as a DOM (Document Object Model) that can be treated with its specific APIs (including an explicit conversion to XML - TODO: link to an example). On the other hand, jrawio provides classes compliant with the Java Beans specifications, including support bound properties that make it easier to use them e.g. in Swing based applications (furthermore blueMarine, another product by Tidalwave, uses those classes for recording metadata into an internal database which makes it easier to browse for metadata items in large media collections). In the past, public and private email exchanges clarified that some people is finding this way of managing metadata convenient and preferrable to the DOM approach.

For this reason, we should evaluate the possibility of making those classes part of a public API. This task depends on a naming convention review, starting from package names.

Up to version 1.5.5

Up to version 1.5.5, the packages in jrawio are the following ones:

Proposals for the future

*** THIS SECTION IS JUST A DRAFT ***

Updated 11 Dec 2009, 13:35 CET

The assessment of the current package names reveals a number of issues:

1. a number of inconsistencies
2. there's no clear separation between public and private packages
3. some package names are driven by the format name, while the camera manufacturer could be a better option

Furthermore, some people asked for a "neutral" project namespace, not related with tidalwave.it. With this respect, we believe that it's also needed not to have any relationship neither with the project name (jrawio or reajent) that could be changed in future (e.g. because somebody trademarks it) nor with the forge where the project is hosted (since it could be changed for any reason).

An idea to be still evaluated is to use 'org.rawdarkroom.imageio' as the new namespace.

In order to address issue #2, three explicit subpackages could be used:

org.rawdarkroom.XXX.*
org.rawdarkroom.XXX.spi.*
org.rawdarkroom.XXX.impl.*

POSSIBLE VARIANT: dropping "" for public packages.This seems to get the most consensus.

#1 would be used for parts of the API used by application programmers; #2 for parts of the API used by implementors of parts of the codec or the processor, #3 for all the rest that is not public.

For issue #3 a proposal is:

org.rawdarkroom.XXX.impl.reader.nikon
org.rawdarkroom.XXX.impl.reader.canon
org.rawdarkroom.XXX.metadata.nikon
org.rawdarkroom.XXX.metadata.canon

Multiple formats (e.g. CRW and CR2 by Canon) are handled inside the same package, with proper naming of the classes.

In this way we can deal with the possibility that multiple manufacturers use formats with the same name.

Stuff for DNG would go into an *.adobe package (the alternative is *.dng, but *.adobe seems more consistent with *.nikon and *.canon). Stuff for TIFF, being functional to supporting TIFF-based formats, should go partly under the *.metadata.tiff and partly under *.spi.blabla.

For class names: NEFMakerNote / NEFMetadata (as in the current version) or NEFNikonMakerNote / NEFNikonMetadata?

For reajent, the proposal is to split packages as:

org.rawdarkroom.codec.*
org.rawdarkroom.codec.spi.*
org.rawdarkroom.codec.impl.*
org.rawdarkroom.processor.*
org.rawdarkroom.processor.spi.*
org.rawdarkroom.processor.impl.*

All packages would be initially renamed into *.impl. with classes "blessed" to be part of the public API incrementally moved to *.

Also, we need some general review for class names (e.g. using lower-case Raw in place of RAW, but also for acronyms such as NEF, since it is the current naming convention for Java, etc...).

To be solved if auxiliary beans for metadata (e.g. org.rawdarkroom.metadata.nikon.NikonLensInfo) should keep the manufacturer name or not (e.g. org.rawdarkroom.metadata.nikon.LensInfo).  Also, ArwMakerNote/MrwMakerNote or ArwMinoltaMakerNote/MrwMinoltaMakerNote or MinoltaMakerNote1/MinoltaMakerNote2?

No more public byte[] getLensInfoAsBytes() / public NikonLensInfo getLensInfo(); rename to public byte[] getLensInfo() / public NikonLensInfo getLensInfoObject().

Follows a *DRAFT* with the details about how classes and packages will be renamed.