This is my "Lenya's posting day" ! :)
On Wed, 25 Feb 2009 00:03:30 +0100, Andreas Hartmann <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
