lenya-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Florent André <florent.andre-...@4sengines.com>
Subject Re: Suggestion about the document & repository API (Re: LenyaDocWritingTransformer)
Date Mon, 23 Mar 2009 21:58:37 GMT
This is my "Lenya's posting day" ! :)


On Wed, 25 Feb 2009 00:03:30 +0100, Andreas Hartmann <andreas@apache.org>
wrote:
> Hi André,
> 
> Florent André schrieb:
[…]
> 
>>>>>> If I can do a suggestion, a documentation on "how to create document
>>>>> from
>>>>>> scratch" could be useful.
>>>>> Yes, I also think this is too complex. The DocumentManager is the
>>>>> original approach, but now I think we should rather add the
respective
>>>>> methods to the repository classes:
>>>>>
>>>>> Area.addDocument(…)
>>>>> SiteStructure.addLink(Node node, Document document)
>> 
>> This methods sound pretty cool !
> 
> Would you like to file an enhancement bug?

Yes, sure ! But I'not sure that I have require competencies to lead that...
But I will try ! { be kind pleeeeease :) }


> 
>>>> On the same subject, I think that it will be interesting to have this
>>>> getter/setter in the document API :
>>> thanks a lot for your suggestions!
>>>
>>>> document.setVisibleInNav();
>>> IMO this would violate SoC – the visibility of the document itself
>> isn't
>>> changed, but the visibility of the link in the site structure. I think
>>> the current API is sufficient:
>>>
>>> document.getLink().getNode().setVisible(boolean)
>> 
>> The api we have : 
>> getPath() : This is a shortcut to getLink().getNode().getPath().
>> 
>> Yes, getPath just send and information and setVisibleInNav() do an
>> action... but for a user I think that a direct relation beetween the
>> document and his visibility in navigation is more affordable...
> 
> IMO document.getPath() is also only a compromise. If we start copying 
> all methods of Node and Link in Document, we end up with a pretty 
> cluttered API. IMO orthogonality is much more important than reducing 
> verbosity.

Ok, I think that I begin to understand what you really mean by
orthogonality... I search rapidly on web, and I find that about horto :
"More generally, in programming languages, orthogonality means design so
that changes in one thing don’t effect another" (source :
http://mindprod.com/jgloss/orthogonal.html)

That is good ? do you have a cool resources ?

> 
> Another problem is that we would tightly couple the Document API and the 
> Site API. For instance, it would be very hard to have multiple 
> occurences of a document in the site tree. When there is only 
> Document.getLink(), the only necessary change would be 
> Document.getLinks(). 

Yes, this can be a very cool possibility ! 
Actually I work on an company's intranet and the CMS was the "Alias
function". This is, I think, the user front end of document.getlinks().
This functionality allow to have the same document (1 unique "real
document") in many topics.
An enhancement bug ? ;)


> If we don't use an orthogonal, loosely coupled API, 
> each small conceptual change will have a huge impact on client code 
> (consider backwards compatibility and migration efforts).
> 
> 
>>>> document.setMetadata();
>>> What would be the argument(s) of this method?
>> 
>> An xml doc ? A java collection or an hastable can be possible, but IMO
>> the
>> xml is more in the "spirits" of Lenya/Cocoon, and allow more
flexibility.
> 
> What is an XML doc in this context? I assume a DOM object? DOM objects 
> are just a special case of XML handling – SAX, StAX, XML strings etc. 
> are equally important – therefore it is IMO arguable to add XML 
> input/output methods to an API. Another reason is that the XML has to be 
> standardized, which raises the questions of versioning, backwards 
> compatibility etc.
> 
> OTOH, an XML-based meta data API would conform to REST principles. The 
> XML would be a representation of the meta data, suitable for read/write 
> operations e.g. via HTTP from a JavaScript-based GUI. I think 
> elaborating on this is worth its own thread. Feel free to start one :)

I will learn a little before start a new thread...

> 
> 
>>>> document.setContent();
>>> What would be the argument(s) of this method? IMO the methods
>>> Document.getIn/OutputStream() cover all i/o requirements. We should
keep
>>> the API as orthogonal as possible, e.g. don't add type conversion
>>> methods (String/InputStream/…) to the Document interface.
>> 
>> IMO, the simplier way to think is : OKAY ! I want to add content in my
>> document, so I do document.setcontent(xmlDoc).
> 
> Again, an XML document is just an abstract concept. Apart from that, 
> XML-based documents are a special case of documents (think of image 
> documents etc.). I wouldn't like to add resource-type specific 
> functionality to the core API.

Ok, I understand, and because I'm "fond of" in "text document" now, I
totally keep of image document...

> 
> 
>> But, in the current api the way to think is (if I am OK with the coding
>> way) :
>> - OKAY, ! I want to add content in my document, so :
>> -- I have to get the write tool (cocoon.source.sourceUtil.writeDom)
>> -- and put in : 
>> ---- outputStream (?? An output stream to get content in ??)
> 
> That's a typical way to write content to an object, see e.g.
> o.a.excalibur.source.ModifiableSource.getOutputStream()
> 
> Another option would be to use Document.setInputStream(InputStream) like 
> it is supported by JCR properties. I'm not sure which option is
> preferrable.

not comment, just : I have to learn ! :)

> 
> 
>> ---- content (xmlDoc)
>> 
>> And, personally, I find strange to tell a "parent object"
(cocoon.source)
>> to write a content in a "child object" (lenya object)...
> 
> I don't quite understand this parent-child relation – why would the 
> source be the parent of the "lenya object" (I guess you mean document)?

In fact, when I study coding, I learn the "encapsulation" concept (a poor
encapsulation concept I think now... a non computer school that spend
coding lesson...) :
parent define (sub-)routine and child implement more "abstract" methode :
child have parents in and fire parent functions. Child can do all that
parent do, but better...


> 
> 
>> I understand the problematic of orthogonal conception, but this is a
>> problem to have a :
>> doc.setcontent(dom content);
>> doc.setcontent(sax content);
>> ?
> 
> What would "SAX content" be? Should Document implement ContentHandler? I 
> don't think this would be a good idea. Or do you mean e.g. an Excalibur 
> XMLizable?
> 
> […]
> 
>> but this make me thinking (caution : I don't learn on this aspect for
>> now,
>> so I speak without know) :
>> How do you think about a method like :
>> - Document.setWorkflowStatus(?? state);
> 
> I agree that workflow handling is too complicated at the moment, but IMO 
> we should rather simplify and extend the adapter pattern that we already 
> use:
> 
>    Workflowable workflowable = new DocumentWorkflowable(document);
>    workflowable.invoke("edit");

I have to look at this...

> 
> 
[...]
>>>> document.setParams();
>>> What params would that be?
>> 
>> I think to other params that show in the create a new document UI
>> (creator,
>> subject, rights and also assets, jobs scheduled,...)and in a more
general
>> way, specific parameters on specific resources.
> 
> I'm afraid that would be a good example for the Magic Container 
> antipattern (http://c2.com/cgi/wiki?MagicContainer). 
> Document.setParams() would not only open the gates of documentation 
> hell, it would also lead to client code that is extremely hard to 
> understand. 

Ok... I understand, thank for the freezy shower ! :)


[...]

> 
> IMO this should need two steps to emphasize the separation of document 
> repository and site structure:
> 
> Document doc = area.add(…);
> Node node = area.getSite().getNode(path);
> Link link = node.addLink(doc);

Can you explain me (or send a resource) the relation between area / site /
node / link and document... The main think I don't really understand is the
"node" concept : 
- a site contains nodes 
- a node can contains links with other documents or other nodes 

That is ?


> 
> 
> BTW, my comments are not at all meant to discourage you, quite the 
> contrary is the case. I hope that discussing each single suggestion is 
> more encouraging than letting them rot on the mailing list archive heap
:)

Yes for sure ! You make me learn, I like to learn.. so big thanks ! :)

Don't worry if I answer after a long time, but I have some hot
subjects, few time and I prefer to think, learn & understand a little
before post...

sayonara :)

> 
> -- Andreas

---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@lenya.apache.org
For additional commands, e-mail: user-help@lenya.apache.org


Mime
View raw message