commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nicola Ken Barozzi" <nicola...@apache.org>
Subject [Morphos] Java data morphing package - second stab
Date Thu, 06 Jun 2002 17:07:58 GMT
Ok, here is the second stab at it :-)
I'm still crossposting now to other projects that have shown interest.

I have gotten many suggestions privately, so this will contain them +
clarifications, and a concrete example.

This discussion properly resides on the Jakarta Commons mailing list.
To subscribe, send an empty mail to commons-dev-subscribe@jakarta.apache.org

From: "Nicola Ken Barozzi" <nicolaken@apache.org>

> What is Morphos?
> -----------------------------
> Morphos will be a Java Api and implementation for transforming data, in
any
> form it may be: xml, streams, objects.
>
> It focuses on the API and framework, and demands implementation to other
> projects-modules wherever possible.
>
>
> Why Morphos?
> -----------------------------
> Morphos starts from a need around a community of developers, with an
initial
> charter committed in Jakarta Commons Sandbox.

[...]

> What does it do?
> -----------------------------
>  Morphos should simply do:
>
>  data  --> morphos ---> data
>
>  Data can be:
>    - stream
>    - events
>    - objects
>
> I don't see other basic generic "data" types, since files and such can
> become streams and viceversa without any format or form conversion.
> I want a *very* simple api, with no duplicated methods.
> IE having get(Stream) and get(File) is not necessary IMO, since they do
the
> same thing.
> The main API must be very simple. We can always add helper classes.

[...]

Ok, but in Concrete?
 ------------------------------
>
> Here is the proposed API, all in package org.apache.commons.morphos:
>
> /**
>  * The interface that is implemented by classes that morph.
>  * It uses two params and not a return value to make it usable with
>  * event based Objects (contenthandlers).
>  * Parameters are key pairs, used to configure the Morpher.
>  * Events in the Morpher are notified by registering a listener.
>  */
> public interface Morpher {
>
>     void morph(Object input, Object output) throws MorphException.
> IOException;
>
>     void addParameter(String paramName, String paramValue);
>     String getParameter(String paramName);
>     void remove Parameter(String paramName);
>     String[] getParameterNames();
>     String[] getParameterValues();
>
>     void addNotificationListener(NotificationListener nl);
>     void removeNotificationListener(NotificationListener nl);
>     void clearNotificationListeners();
>
> }

 /**
  * The interface that is implemented by classes that morph.
  * It uses two params and not a return value to make it usable with
  * event based Objects (contenthandlers).
  * Events in the Morpher are notified by registering a listener.
  * [new] parameters are managed with beans get/set methods
  *            *none* are mandatory
  */
 public interface Morpher {

     void morph(Object input, Object output) throws MorphException.
 IOException;

     void addNotificationListener(NotificationListener nl);
     void removeNotificationListener(NotificationListener nl);
     void clearNotificationListeners();

 }

[Clarification]
Why not
  Object morph(Object input) throws MorphException, IOException;
?

Because if the output object is a SAX handler, the morphing doesn't take
place, and this is not evident.
Any other pros-cons?

[Clarification 2]
Why use Object as input and output?
Why not use different types?

Genericity.
See the below comments after the Factory/Manager.

> /**
>  * A Morpher made out of a sequence of morphers.
>  */
>
> public interface MorpherPipeline extends Morpher {
>
>     void addStage(Morpher nextMorpher);
>
> }

This remains.

>
> /**
>  * The Factory for Morphers.
>  * There is a getDefaultFactory method for easy use.
>  * Used in frameworks it's better not to use it and rely on
>  * services that give the proper MorpherFactory.
>  */
> public abstract MorpherFactory  {
>
>     Morpher getMorpher(DataType inputType, DataType outputType);
>     Morpher getMorpher(name);
>
>     Morpher getPreparedMorpher(DataType inputType, DataType outputType);
>     Morpher getPreparedMorpher(name);
>
>     static MorpherFactory getDefaultFactory();
> }

 /**
  * The Morphers' manager.
  * There is a getDefaultFactory method for easy use.
  * Used in frameworks it's better not to use it and rely on
  * services that give the proper MorpherFactory.
  */
 public interface MorpherManager  {

     Morpher getMorpher(DataType inputType, DataType outputType);
     Morpher getMorpher(name);

     Morpher getPreparedMorpher(DataType inputType, DataType outputType);
     Morpher getPreparedMorpher(name);
 }

I've removed the static method, and made it an interface.
It will be the MorpherManager implementation that can use this pattern.

Why not *Factory?
Because it does more than just create them.

[Clarification 2]
Why is a Manager needed?

Because (see clarification 1) any Morpher instance is supposed to be an
implementation that is guaranteed to work with a determined kind of Objects
(a subset); this enforcement is done by the Manager.


> /**
>  * Describes what the format of the data is.
>  * It consists of a mimetype (format) and a dataForm (representation).
>  * For example a gif image file and a jped image file have a different
> mimetype but same dataform (file).
>  * An SVG file and an SVG DOM in memory have same mimetype but different
> dataform.
>  */
> public interface DataType {
>
>     void setMimeType(String mimetype);
>     void setDataForm(String format);
>
>     String getMimeType();
>     String getDataForm();
>
> }

This becomes:
 /**
  * Describes what the format of the data is.
  * It consists of a mimetype (format) and a dataForm (representation).
  * For example a gif image file and a jped image file have a different
 mimetype but same dataform (file).
  * An SVG file and an SVG DOM in memory have same mimetype but different
 dataform.
  */
 public class DataType {

     ....

     public DataType (String mimetype, String format) {
        ...
     }

     public DataType () {
        ...
     }

     void setMimeType(String mimetype){...};
     void setDataForm(String format){...};

     String getMimeType(){...};
     String getDataForm(){...};

 }


[Example]

/* Create the Manager that gives me the morphers */
MorpherManager  mmanager = new SimpleMorpherManager("mmanager-conf.xml");

/* Get a jaxp Morpher by name */
Morpher jaxpmorpher =  mmanager.getMorpher("jaxp");

jaxpmorpher.setStylesheet("transform.xml");

/* Get a Morpher that serializes an XML dom to a stream */
Morpher streammorpher =
  mmanager.getMorpher(
     new DataType("text/xml", "object/dom"),
     new DataType("text/xml", "stream/unix")
   );

Chain the two:

MorpherPipeline mpipeline =  new SimpleMorpherPipeline();
mpipeline.addStage(jaxpmorpher );
mpipeline.addStage(streammorpher );

try{
  mpipeline.morph(myDomObject, outputstream);
}
catch(IMorphException ioe){
 .....}
catch(IOException ioe){
.....}



--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------


--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message