Hi André,
Florent André schrieb:
This mail is don't dead ! (but me nearly killed by work :)
Just to be clear, this mail is just a suggestion, a personnal idea and
surely not a critize or a "super man feeling", I know the big (and good)
work do by the Lenya community.
sure, don't worry :) Your suggestions are very much appreciated, in fact
I think a lot more of discussions like this should happen.
[…]
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?
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.
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(). 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 :)
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.
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.
---- 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)?
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");
document.setNavTitle();
Same as with setVisibleInNav().
document.setTitle();
I guess that would be an implicit mapping to the DC element "title"? I'm
not sure if this can be generalized. What do the others think?
In my mind : setTitle() = set the navigation title
IMO this is the same issue like with Document.getPath().
Usable if we can modify the navigation title and/or create an "empty"
document (like a new document in an office suite)
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. We had methods like this before in the Lenya codebase, and
took great pains to get rid of them.
------------
In fact, the "concept" behind this suggestions is the "user centric
approach".
The spirits of this approach is : if we consider the "user uses cases" -
what a user want to do - how can we make this as "natural" - affordable,
usable, intuitive - as possible ?
I understand your desire for simplification, but a bit less verbosity
isn't worth reducing orthogonality and increasing the number of methods
in an API. The Lenya API is very large and complex even now (when
compared e.g. to JCR).
A table like that can help to define the what and the how:
What user want to do | How user do
-----------------------------------------------------------------------------
create a document |
area|node|sitestructure.create()
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);
-----------------------------------------------------------------------------
add content to the document | document.setcontent()
-----------------------------------------------------------------------------
set the document visibility | document.setvisibility
These have already been discussed above.
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 :)
-- Andreas
--
Andreas Hartmann, CTO
BeCompany GmbH
http://www.becompany.ch
Tel.: +41 (0) 43 818 57 01
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
