You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Antonio Gallardo <ag...@agssa.net> on 2004/07/12 12:58:12 UTC
Clean up exception not throwed in some methods over the code.
Hi:
I also have another question. We have some exceptions that are not being
throw at all, but the method declare it. Sample at line 76:
The constructor does not throw any of the declared Exceptions.
Can we clean up this code? There are cca 150 similar places over the code.
Best Regards,
Antonio Gallardo
Re: Clean up exception not throwed in some methods over the code.
Posted by Antonio Gallardo <ag...@agssa.net>.
Vadim Gritsenko dijo:
> Carsten Ziegeler wrote:
>
>>Antonio Gallardo wrote:
>>
>>
>>>Antonio Gallardo dijo:
>>>
>>>
>>>>Hi:
>>>>
>>>>I also have another question. We have some exceptions that are not
>>>>being throw at all, but the method declare it. Sample at line 76:
>>>>
>>>>
>>>Filling the missing link :(
>>>
>>>http://cvs.apache.org/viewcvs.cgi/cocoon-2.1/src/blocks/xsp/ja
>>>va/org/apache/cocoon/components/language/markup/Logicsheet.jav
>>>a?annotate=1.3
>>>
>>>
>>>>The constructor does not throw any of the declared Exceptions.
>>>>
>>>>Can we clean up this code? There are cca 150 similar places
>>>>
>>>>
>>>over the code.
>>>
>>>
>>In general I'm +1 for such changes, but unfortunately these are
>> incompatible
>>changes! For example, if a client has a try/catch clause for such
>>an exception and you remove it from the list, then the client code
>>is not compilable anymore as the exception is not thrown inside
>>the block anymore.
>>So, I would say, let's leave them there (but I'm not opposed to remove
>> them
>>:) ).
>>
>>
>
> "Throws" declarations can be safely removed in the situation when method
> implements an interface. Interface will have exception declarations, and
> interface implementation might not have them if it does not need them.
>
> In all other situations, Carsten is right - this might cause backward
> incompatibility. This is important for user-facing classes. Should we
> start marking classes as internal, like "<b>INTERNAL!!!</b>" in javadoc
> or some such?
You got on the right thing! For a cleaner code, I believe we need to
define what is supposed to be internal API and what not. Sharing a lot of
code also just because it has a "public" tag does not mean want users use
it.
Best Regards,
Antonio Gallardo
Re: Clean up exception not throwed in some methods over the code.
Posted by Sylvain Wallez <sy...@apache.org>.
Vadim Gritsenko wrote:
> Carsten Ziegeler wrote:
>
>> Antonio Gallardo wrote:
>>
>>> Antonio Gallardo dijo:
>>>
>>>
>>>> Hi:
>>>>
>>>> I also have another question. We have some exceptions that are not
>>>> being throw at all, but the method declare it. Sample at line 76:
>>>>
>>>
>>> Filling the missing link :(
>>>
>>> http://cvs.apache.org/viewcvs.cgi/cocoon-2.1/src/blocks/xsp/ja
>>> va/org/apache/cocoon/components/language/markup/Logicsheet.jav
>>> a?annotate=1.3
>>>
>>>
>>>> The constructor does not throw any of the declared Exceptions.
>>>>
>>>> Can we clean up this code? There are cca 150 similar places
>>>
>>> over the code.
>>>
>>
>> In general I'm +1 for such changes, but unfortunately these are
>> incompatible
>> changes! For example, if a client has a try/catch clause for such
>> an exception and you remove it from the list, then the client code
>> is not compilable anymore as the exception is not thrown inside
>> the block anymore.
>> So, I would say, let's leave them there (but I'm not opposed to
>> remove them
>> :) ).
>
>
> "Throws" declarations can be safely removed in the situation when
> method implements an interface. Interface will have exception
> declarations, and interface implementation might not have them if it
> does not need them.
Great care must be taken however about classes that can be extended, as
not declaring the thrown exception from the base class or interface
forbids subclasses to throw them.
An example of this can be found in
o.a.c.components.ExtendedComponentSelector.initialize() where exceptions
have to be wrapped in a RuntimeException because the parent class has
omitted the throws clause.
> In all other situations, Carsten is right - this might cause backward
> incompatibility. This is important for user-facing classes. Should we
> start marking classes as internal, like "<b>INTERNAL!!!</b>" in
> javadoc or some such?
+1000!
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: [Vote] Marking internal classes
Posted by Guido Casper <gc...@s-und-n.de>.
Reinhard Poetz wrote:
> Unico Hommes wrote:
>> Guido Casper wrote:
>>> Sorry, I think I was not clear (my fault). I intended the vote to be
>>> about marking (like within javadocs) either:
>>> -internal classes
>>> or (the opposite):
>>> -published classes
>>>
>>> The first is what Vadim suggested and most simple to do (there are
>>> just a few internal classes).
>>>
>>> The latter opens the door to further classify classes/interfaces.
>>>
>>
>> OK, I get it now. Let's start with marking internal classes then. This
>> is what is needed most ATM in order to allow the cocoon internals to
>> more freely evolve.
>
> +1
So I summarize that there is a strong preference to marking internal
classes and let "public" be the default.
I'll remove my crappy doclet task then. I wasn't very happy about it
anyway. I'll continue thinking about better ways to document the various
APIs at different levels.
Maybe they should just be separated into different Java packages.
Guido
Re: [Vote] Marking internal classes
Posted by Reinhard Poetz <re...@apache.org>.
Unico Hommes wrote:
> Guido Casper wrote:
>
>> Unico Hommes wrote:
>>
>>> Guido Casper wrote:
>>>
>>>> Guido Casper wrote:
>>>>
>>>>> Vadim Gritsenko wrote:
>>>>>
>>>>>> In all other situations, Carsten is right - this might cause
>>>>>> backward incompatibility. This is important for user-facing
>>>>>> classes. Should we start marking classes as internal, like
>>>>>> "<b>INTERNAL!!!</b>" in javadoc or some such?
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> What about introducing @cocoon.usage tags I proposed a while ago
>>>>> like:
>>>>> @cocoon.usage published
>>>>>
>>>>> or:
>>>>> @cocoon.usage flowscript
>>>>>
>>>>> etc.
>>>>>
>>>>> This might someday also be used to generate separate Javadocs for
>>>>> different APIs.
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> Hm, noone (but me :-) seems to like the idea.
>>>>
>>>> So maybe it's a good idea to first have a quick vote about whether
>>>> to mark internal classes as such or to mark "published
>>>> classes/interfaces" as such (and then decide how to mark them).
>>>>
>>>
>>> +1
>>
>>
>>
>> Sorry, I think I was not clear (my fault). I intended the vote to be
>> about marking (like within javadocs) either:
>> -internal classes
>> or (the opposite):
>> -published classes
>>
>> The first is what Vadim suggested and most simple to do (there are
>> just a few internal classes).
>>
>> The latter opens the door to further classify classes/interfaces.
>>
>
> OK, I get it now. Let's start with marking internal classes then. This
> is what is needed most ATM in order to allow the cocoon internals to
> more freely evolve.
+1
--
Reinhard
Re: [Vote] Marking internal classes
Posted by Unico Hommes <un...@hippo.nl>.
Guido Casper wrote:
> Unico Hommes wrote:
>
>> Guido Casper wrote:
>>
>>> Guido Casper wrote:
>>>
>>>> Vadim Gritsenko wrote:
>>>>
>>>>> In all other situations, Carsten is right - this might cause
>>>>> backward incompatibility. This is important for user-facing
>>>>> classes. Should we start marking classes as internal, like
>>>>> "<b>INTERNAL!!!</b>" in javadoc or some such?
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> What about introducing @cocoon.usage tags I proposed a while ago like:
>>>> @cocoon.usage published
>>>>
>>>> or:
>>>> @cocoon.usage flowscript
>>>>
>>>> etc.
>>>>
>>>> This might someday also be used to generate separate Javadocs for
>>>> different APIs.
>>>
>>>
>>>
>>>
>>> Hm, noone (but me :-) seems to like the idea.
>>>
>>> So maybe it's a good idea to first have a quick vote about whether
>>> to mark internal classes as such or to mark "published
>>> classes/interfaces" as such (and then decide how to mark them).
>>>
>>
>> +1
>
>
> Sorry, I think I was not clear (my fault). I intended the vote to be
> about marking (like within javadocs) either:
> -internal classes
> or (the opposite):
> -published classes
>
> The first is what Vadim suggested and most simple to do (there are
> just a few internal classes).
>
> The latter opens the door to further classify classes/interfaces.
>
OK, I get it now. Let's start with marking internal classes then. This
is what is needed most ATM in order to allow the cocoon internals to
more freely evolve.
--
Unico
Re: [Vote] Marking internal classes
Posted by Guido Casper <gc...@s-und-n.de>.
Unico Hommes wrote:
> Guido Casper wrote:
>
>> Guido Casper wrote:
>>
>>> Vadim Gritsenko wrote:
>>>
>>>> In all other situations, Carsten is right - this might cause
>>>> backward incompatibility. This is important for user-facing classes.
>>>> Should we start marking classes as internal, like
>>>> "<b>INTERNAL!!!</b>" in javadoc or some such?
>>>
>>>
>>>
>>>
>>> What about introducing @cocoon.usage tags I proposed a while ago like:
>>> @cocoon.usage published
>>>
>>> or:
>>> @cocoon.usage flowscript
>>>
>>> etc.
>>>
>>> This might someday also be used to generate separate Javadocs for
>>> different APIs.
>>
>>
>>
>> Hm, noone (but me :-) seems to like the idea.
>>
>> So maybe it's a good idea to first have a quick vote about whether to
>> mark internal classes as such or to mark "published
>> classes/interfaces" as such (and then decide how to mark them).
>>
>
> +1
Sorry, I think I was not clear (my fault). I intended the vote to be
about marking (like within javadocs) either:
-internal classes
or (the opposite):
-published classes
The first is what Vadim suggested and most simple to do (there are just
a few internal classes).
The latter opens the door to further classify classes/interfaces.
Guido
Re: [Vote] Marking internal classes
Posted by Unico Hommes <un...@hippo.nl>.
Guido Casper wrote:
> Guido Casper wrote:
>
>> Vadim Gritsenko wrote:
>>
>>> In all other situations, Carsten is right - this might cause
>>> backward incompatibility. This is important for user-facing classes.
>>> Should we start marking classes as internal, like
>>> "<b>INTERNAL!!!</b>" in javadoc or some such?
>>
>>
>>
>> What about introducing @cocoon.usage tags I proposed a while ago like:
>> @cocoon.usage published
>>
>> or:
>> @cocoon.usage flowscript
>>
>> etc.
>>
>> This might someday also be used to generate separate Javadocs for
>> different APIs.
>
>
> Hm, noone (but me :-) seems to like the idea.
>
> So maybe it's a good idea to first have a quick vote about whether to
> mark internal classes as such or to mark "published
> classes/interfaces" as such (and then decide how to mark them).
>
+1
--
Unico
Re: [Vote] Marking internal classes
Posted by Sylvain Wallez <sy...@apache.org>.
Guido Casper wrote:
> Guido Casper wrote:
>
>> Vadim Gritsenko wrote:
>>
>>> In all other situations, Carsten is right - this might cause
>>> backward incompatibility. This is important for user-facing classes.
>>> Should we start marking classes as internal, like
>>> "<b>INTERNAL!!!</b>" in javadoc or some such?
>>
>>
>>
>> What about introducing @cocoon.usage tags I proposed a while ago like:
>> @cocoon.usage published
>>
>> or:
>> @cocoon.usage flowscript
>>
>> etc.
>>
>> This might someday also be used to generate separate Javadocs for
>> different APIs.
>
>
> Hm, noone (but me :-) seems to like the idea.
Lack of answer doesn't mean people don't like the idea. I for one
already proposed such a thing, but the work for marking classes is huge
and not very motivating ;-)
> So maybe it's a good idea to first have a quick vote about whether to
> mark internal classes as such or to mark "published
> classes/interfaces" as such (and then decide how to mark them).
+1 !
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: [Vote] Marking internal classes
Posted by Giacomo Pati <gi...@apache.org>.
Reinhard Poetz wrote:
> Guido Casper wrote:
>> So maybe it's a good idea to first have a quick vote about whether to
>> mark internal classes as such or to mark "published
>> classes/interfaces" as such (and then decide how to mark them).
>
>
>
> +1
>
> I also propose to separate the cocoon.jar into two parts: One that
> contains all interfaces that can be implemented and all classes that can
> be used or extended and a second jar that contains the rest which is
> only used internally. After migrating to Suversion this can be done
> without breaking the history because this will also require some file
> moving. IMO this step is necessary to separate our blocks from Cocoon
> core, isn't it?
That's what was already proposed 6 month ago when discussing the 2.2
layout. Separation of classes into API, core, private and public classes
(and several ones for the blocks). I'm still +1 for that.
I've also seen (again) some discussion about using Maven (which would
help building multiple jars just easy).
--
Giacomo Pati
Otego AG, Switzerland - http://www.otego.com
Orixo, the XML business alliance - http://www.orixo.com
Re: [Vote] Marking internal classes
Posted by Reinhard Poetz <re...@apache.org>.
Unico Hommes wrote:
>>>> So we have
>>>>
>>>> - cocoon-spi.jar
>>>> "Interfaces that function as SPI's are for instance the different
>>>> sitemap
>>>> component interfaces: Transformer, ProcessingPipeline, Reader,
>>>> Matcher, etc."
>>>>
>>>> - cocoon-api.jar
>>>> "An example of an API level interface is for instance Processor
>>>> and the different
>>>> environment related interfaces: Request, Context, Environment, etc."
>>>>
>>>> - cocoon-core.jar
>>>> Implementations of component interfaces for (re)use
>>>>
>>>> - cocoon-internal.jar
>>>> everything that should only be used internally
>>>>
>>>
>>> Perhaps we don't need a separate jar for internal classes. Marking
>>> them with javadoc tags should be enough.
>>
>>
>>
>>
>> Having a separate cocoon-internal.jar makes block development easier
>> because I wouldn't import it into my classpath.
>>
>
> OK, good point.
>
>>>> Additionally we can create modules containing the differnet
>>>> environment implementations:
>>>>
>>>> - servlet-environment.module.jar
>>>> - commandline-environment.module.jar
>>>> - ...
>>>>
>>>> A module compiles against cocoon-api.jar.
>>>>
>>>
>>> Exactly.
>>>
>>>> Everything else is part of a block. A block compiles against
>>>> cocoon-core.jar and cocoon-spi.jar.
>>>
>>>
>>>
>>> .. and also cocoon-api.jar but not because it contains classes that
>>> implement API interfaces.
>>
>>
>>
>>
>> Sorry, I don't understand this.
>>
>
> Many sitemap components make use of API interfaces such as Request,
> Response, etc. Blocks may have usage relation to them but must not
> have an implements relation to them.
Thanks you, didn't thought about this.
>
>>>> I'm not sure where to put the Flow implementations, XSP and the
>>>> different templating engines.
>>>>
>>> Hmm, yes. XSP is currently a block, I say we leave it like that for
>>> now. The flow implementation could be part of the core but is
>>> perhaps better manageable as a separate unit. The flow Interpreter
>>> interface is part of the SPI so by the above reasoning that blocks
>>> are SPI implementations this would mean it should be a block. OTOH
>>> it is definately different from other blocks. Maybe we need another
>>> concept for this. Also because the core is still quite big. I
>>> remember some time ago Stefano talked about "aspects" in reference
>>> to XSP.
>>
>>
>>
>>
>> I understand but I'm not sure if having so many different units like
>> "modules", "blocks" and "aspects" helps to make Cocoon more
>> understandable ...
>>
>
> May be a debatable point. I tend to think that with a codebase as
> large as Cocoon's a lot of stuff can be factored into separate modules
> before fragmentation starts to get in the way of understandability.
Probably yes.
> But with the separation in your proposal we already gain a lot so
> let's start there.
As so often, evolution instead of revolution seems to be the way to go.
After this refactoring we can make a break and look what we already
reached and which issues are still unsolved.
I'll prepare a vote after migrating to Subversion.
More thoughts (we have some time until the migration has finished :-)
--
Reinhard
Re: [Vote] Marking internal classes
Posted by Unico Hommes <un...@hippo.nl>.
Reinhard Poetz wrote:
> Unico Hommes wrote:
>
>> Reinhard Poetz wrote:
>>
>>> Unico Hommes wrote:
>>>
>>>> Sylvain Wallez wrote:
>>>>
>>>>> Unico Hommes wrote:
>>>>>
>>>>>> Reinhard Poetz wrote:
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> <snip/>
>>>>>
>>>>>>> I also propose to separate the cocoon.jar into two parts: One
>>>>>>> that contains all interfaces that can be implemented and all
>>>>>>> classes that can be used or extended and a second jar that
>>>>>>> contains the rest which is only used internally. After migrating
>>>>>>> to Suversion this can be done without breaking the history
>>>>>>> because this will also require some file moving. IMO this step
>>>>>>> is necessary to separate our blocks from Cocoon core, isn't it?
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>> Good idea, but IMO this complements marking the classes, as if you
>>>>> load the full Cocoon in an Eclipse project, completion will show
>>>>> all classes. A notice at the beginning of the javadoc helps in
>>>>> noticing that you use something that's forbidden.
>>>>>
>>>>>> I like this too. There could be more than two parts though. There
>>>>>> is the API part that contains interfaces used to embed cocoon
>>>>>> into a certain environment. The SPI interfaces developers
>>>>>> implement to extend the functionality of Cocoon. The different
>>>>>> API implementations that we have (CLI, Servlet). And finally the
>>>>>> core components.
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> Can you elaborate on the difference between API and SPI?
>>>>
>>>>
>>>>
>>>> This is the way they separate their code into modules at Avalon. I
>>>> like it because it clearly marks the different functions separate
>>>> parts of the code play in an application. Interfaces that function
>>>> as SPI's are for instance the different sitemap component
>>>> interfaces: Transformer, ProcessingPipeline, Reader, Matcher, etc.
>>>> An example of an API level interface is for instance Processor and
>>>> the different environment related interfaces: Request, Context,
>>>> Environment, etc.
>>>
>>>
>>>
>>> So we have
>>>
>>> - cocoon-spi.jar
>>> "Interfaces that function as SPI's are for instance the different
>>> sitemap
>>> component interfaces: Transformer, ProcessingPipeline, Reader,
>>> Matcher, etc."
>>>
>>> - cocoon-api.jar
>>> "An example of an API level interface is for instance Processor and
>>> the different
>>> environment related interfaces: Request, Context, Environment, etc."
>>>
>>> - cocoon-core.jar
>>> Implementations of component interfaces for (re)use
>>>
>>> - cocoon-internal.jar
>>> everything that should only be used internally
>>>
>>
>> Perhaps we don't need a separate jar for internal classes. Marking
>> them with javadoc tags should be enough.
>
>
>
> Having a separate cocoon-internal.jar makes block development easier
> because I wouldn't import it into my classpath.
>
OK, good point.
>>> Additionally we can create modules containing the differnet
>>> environment implementations:
>>>
>>> - servlet-environment.module.jar
>>> - commandline-environment.module.jar
>>> - ...
>>>
>>> A module compiles against cocoon-api.jar.
>>>
>>
>> Exactly.
>>
>>> Everything else is part of a block. A block compiles against
>>> cocoon-core.jar and cocoon-spi.jar.
>>
>>
>> .. and also cocoon-api.jar but not because it contains classes that
>> implement API interfaces.
>
>
>
> Sorry, I don't understand this.
>
Many sitemap components make use of API interfaces such as Request,
Response, etc. Blocks may have usage relation to them but must not have
an implements relation to them.
>>> I'm not sure where to put the Flow implementations, XSP and the
>>> different templating engines.
>>>
>> Hmm, yes. XSP is currently a block, I say we leave it like that for
>> now. The flow implementation could be part of the core but is perhaps
>> better manageable as a separate unit. The flow Interpreter interface
>> is part of the SPI so by the above reasoning that blocks are SPI
>> implementations this would mean it should be a block. OTOH it is
>> definately different from other blocks. Maybe we need another concept
>> for this. Also because the core is still quite big. I remember some
>> time ago Stefano talked about "aspects" in reference to XSP.
>
>
>
> I understand but I'm not sure if having so many different units like
> "modules", "blocks" and "aspects" helps to make Cocoon more
> understandable ...
>
May be a debatable point. I tend to think that with a codebase as large
as Cocoon's a lot of stuff can be factored into separate modules before
fragmentation starts to get in the way of understandability. But with
the separation in your proposal we already gain a lot so let's start there.
--
Unico
Re: [Vote] Marking internal classes
Posted by Reinhard Poetz <re...@apache.org>.
Unico Hommes wrote:
> Reinhard Poetz wrote:
>
>> Unico Hommes wrote:
>>
>>> Sylvain Wallez wrote:
>>>
>>>> Unico Hommes wrote:
>>>>
>>>>> Reinhard Poetz wrote:
>>>>
>>>>
>>>>
>>>> <snip/>
>>>>
>>>>>> I also propose to separate the cocoon.jar into two parts: One
>>>>>> that contains all interfaces that can be implemented and all
>>>>>> classes that can be used or extended and a second jar that
>>>>>> contains the rest which is only used internally. After migrating
>>>>>> to Suversion this can be done without breaking the history
>>>>>> because this will also require some file moving. IMO this step is
>>>>>> necessary to separate our blocks from Cocoon core, isn't it?
>>>>>
>>>>>
>>>>>
>>>> Good idea, but IMO this complements marking the classes, as if you
>>>> load the full Cocoon in an Eclipse project, completion will show
>>>> all classes. A notice at the beginning of the javadoc helps in
>>>> noticing that you use something that's forbidden.
>>>>
>>>>> I like this too. There could be more than two parts though. There
>>>>> is the API part that contains interfaces used to embed cocoon into
>>>>> a certain environment. The SPI interfaces developers implement to
>>>>> extend the functionality of Cocoon. The different API
>>>>> implementations that we have (CLI, Servlet). And finally the core
>>>>> components.
>>>>
>>>>
>>>>
>>>> Can you elaborate on the difference between API and SPI?
>>>
>>>
>>> This is the way they separate their code into modules at Avalon. I
>>> like it because it clearly marks the different functions separate
>>> parts of the code play in an application. Interfaces that function
>>> as SPI's are for instance the different sitemap component
>>> interfaces: Transformer, ProcessingPipeline, Reader, Matcher, etc.
>>> An example of an API level interface is for instance Processor and
>>> the different environment related interfaces: Request, Context,
>>> Environment, etc.
>>
>>
>> So we have
>>
>> - cocoon-spi.jar
>> "Interfaces that function as SPI's are for instance the different
>> sitemap
>> component interfaces: Transformer, ProcessingPipeline, Reader,
>> Matcher, etc."
>>
>> - cocoon-api.jar
>> "An example of an API level interface is for instance Processor and
>> the different
>> environment related interfaces: Request, Context, Environment, etc."
>>
>> - cocoon-core.jar
>> Implementations of component interfaces for (re)use
>>
>> - cocoon-internal.jar
>> everything that should only be used internally
>>
>
> Perhaps we don't need a separate jar for internal classes. Marking
> them with javadoc tags should be enough.
Having a separate cocoon-internal.jar makes block development easier
because I wouldn't import it into my classpath.
>> Additionally we can create modules containing the differnet
>> environment implementations:
>>
>> - servlet-environment.module.jar
>> - commandline-environment.module.jar
>> - ...
>>
>> A module compiles against cocoon-api.jar.
>>
>
> Exactly.
>
>> Everything else is part of a block. A block compiles against
>> cocoon-core.jar and cocoon-spi.jar.
>
> .. and also cocoon-api.jar but not because it contains classes that
> implement API interfaces.
Sorry, I don't understand this.
>> I'm not sure where to put the Flow implementations, XSP and the
>> different templating engines.
>>
> Hmm, yes. XSP is currently a block, I say we leave it like that for
> now. The flow implementation could be part of the core but is perhaps
> better manageable as a separate unit. The flow Interpreter interface
> is part of the SPI so by the above reasoning that blocks are SPI
> implementations this would mean it should be a block. OTOH it is
> definately different from other blocks. Maybe we need another concept
> for this. Also because the core is still quite big. I remember some
> time ago Stefano talked about "aspects" in reference to XSP.
I understand but I'm not sure if having so many different units like
"modules", "blocks" and "aspects" helps to make Cocoon more
understandable ...
--
Reinhard
Re: [Vote] Marking internal classes
Posted by Unico Hommes <un...@hippo.nl>.
Reinhard Poetz wrote:
> Unico Hommes wrote:
>
>> Sylvain Wallez wrote:
>>
>>> Unico Hommes wrote:
>>>
>>>> Reinhard Poetz wrote:
>>>
>>>
>>> <snip/>
>>>
>>>>> I also propose to separate the cocoon.jar into two parts: One that
>>>>> contains all interfaces that can be implemented and all classes
>>>>> that can be used or extended and a second jar that contains the
>>>>> rest which is only used internally. After migrating to Suversion
>>>>> this can be done without breaking the history because this will
>>>>> also require some file moving. IMO this step is necessary to
>>>>> separate our blocks from Cocoon core, isn't it?
>>>>
>>>>
>>> Good idea, but IMO this complements marking the classes, as if you
>>> load the full Cocoon in an Eclipse project, completion will show all
>>> classes. A notice at the beginning of the javadoc helps in noticing
>>> that you use something that's forbidden.
>>>
>>>> I like this too. There could be more than two parts though. There
>>>> is the API part that contains interfaces used to embed cocoon into
>>>> a certain environment. The SPI interfaces developers implement to
>>>> extend the functionality of Cocoon. The different API
>>>> implementations that we have (CLI, Servlet). And finally the core
>>>> components.
>>>
>>>
>>> Can you elaborate on the difference between API and SPI?
>>
>>
>> This is the way they separate their code into modules at Avalon. I
>> like it because it clearly marks the different functions separate
>> parts of the code play in an application. Interfaces that function as
>> SPI's are for instance the different sitemap component interfaces:
>> Transformer, ProcessingPipeline, Reader, Matcher, etc. An example of
>> an API level interface is for instance Processor and the different
>> environment related interfaces: Request, Context, Environment, etc.
>
>
>
> So we have
>
> - cocoon-spi.jar
> "Interfaces that function as SPI's are for instance the different
> sitemap
> component interfaces: Transformer, ProcessingPipeline, Reader,
> Matcher, etc."
>
> - cocoon-api.jar
> "An example of an API level interface is for instance Processor and
> the different
> environment related interfaces: Request, Context, Environment, etc."
>
> - cocoon-core.jar
> Implementations of component interfaces for (re)use
>
> - cocoon-internal.jar
> everything that should only be used internally
>
Perhaps we don't need a separate jar for internal classes. Marking them
with javadoc tags should be enough.
> Additionally we can create modules containing the differnet
> environment implementations:
>
> - servlet-environment.module.jar
> - commandline-environment.module.jar
> - ...
>
> A module compiles against cocoon-api.jar.
>
Exactly.
>
> Everything else is part of a block. A block compiles against
> cocoon-core.jar and cocoon-spi.jar.
>
.. and also cocoon-api.jar but not because it contains classes that
implement API interfaces.
> I'm not sure where to put the Flow implementations, XSP and the
> different templating engines.
>
Hmm, yes. XSP is currently a block, I say we leave it like that for now.
The flow implementation could be part of the core but is perhaps better
manageable as a separate unit. The flow Interpreter interface is part of
the SPI so by the above reasoning that blocks are SPI implementations
this would mean it should be a block. OTOH it is definately different
from other blocks. Maybe we need another concept for this. Also because
the core is still quite big. I remember some time ago Stefano talked
about "aspects" in reference to XSP.
--
Unico
Re: [Vote] Marking internal classes
Posted by Reinhard Poetz <re...@apache.org>.
Unico Hommes wrote:
> Sylvain Wallez wrote:
>
>> Unico Hommes wrote:
>>
>>> Reinhard Poetz wrote:
>>
>> <snip/>
>>
>>>> I also propose to separate the cocoon.jar into two parts: One that
>>>> contains all interfaces that can be implemented and all classes
>>>> that can be used or extended and a second jar that contains the
>>>> rest which is only used internally. After migrating to Suversion
>>>> this can be done without breaking the history because this will
>>>> also require some file moving. IMO this step is necessary to
>>>> separate our blocks from Cocoon core, isn't it?
>>>
>> Good idea, but IMO this complements marking the classes, as if you
>> load the full Cocoon in an Eclipse project, completion will show all
>> classes. A notice at the beginning of the javadoc helps in noticing
>> that you use something that's forbidden.
>>
>>> I like this too. There could be more than two parts though. There is
>>> the API part that contains interfaces used to embed cocoon into a
>>> certain environment. The SPI interfaces developers implement to
>>> extend the functionality of Cocoon. The different API
>>> implementations that we have (CLI, Servlet). And finally the core
>>> components.
>>
>> Can you elaborate on the difference between API and SPI?
>
> This is the way they separate their code into modules at Avalon. I
> like it because it clearly marks the different functions separate
> parts of the code play in an application. Interfaces that function as
> SPI's are for instance the different sitemap component interfaces:
> Transformer, ProcessingPipeline, Reader, Matcher, etc. An example of
> an API level interface is for instance Processor and the different
> environment related interfaces: Request, Context, Environment, etc.
So we have
- cocoon-spi.jar
"Interfaces that function as SPI's are for instance the different sitemap
component interfaces: Transformer, ProcessingPipeline, Reader,
Matcher, etc."
- cocoon-api.jar
"An example of an API level interface is for instance Processor and
the different
environment related interfaces: Request, Context, Environment, etc."
- cocoon-core.jar
Implementations of component interfaces for (re)use
- cocoon-internal.jar
everything that should only be used internally
Additionally we can create modules containing the differnet environment
implementations:
- servlet-environment.module.jar
- commandline-environment.module.jar
- ...
A module compiles against cocoon-api.jar.
Everything else is part of a block. A block compiles against
cocoon-core.jar and cocoon-spi.jar.
I'm not sure where to put the Flow implementations, XSP and the
different templating engines.
Any other ideas/thoughts?
--
Reinhard
Re: [Vote] Marking internal classes
Posted by Unico Hommes <un...@hippo.nl>.
Sylvain Wallez wrote:
> Unico Hommes wrote:
>
>> Reinhard Poetz wrote:
>
>
>
> <snip/>
>
>>> I also propose to separate the cocoon.jar into two parts: One that
>>> contains all interfaces that can be implemented and all classes that
>>> can be used or extended and a second jar that contains the rest
>>> which is only used internally. After migrating to Suversion this can
>>> be done without breaking the history because this will also require
>>> some file moving. IMO this step is necessary to separate our blocks
>>> from Cocoon core, isn't it?
>>
>>
>
> Good idea, but IMO this complements marking the classes, as if you
> load the full Cocoon in an Eclipse project, completion will show all
> classes. A notice at the beginning of the javadoc helps in noticing
> that you use something that's forbidden.
>
>> I like this too. There could be more than two parts though. There is
>> the API part that contains interfaces used to embed cocoon into a
>> certain environment. The SPI interfaces developers implement to
>> extend the functionality of Cocoon. The different API implementations
>> that we have (CLI, Servlet). And finally the core components.
>
>
>
> Can you elaborate on the difference between API and SPI?
>
This is the way they separate their code into modules at Avalon. I like
it because it clearly marks the different functions separate parts of
the code play in an application. Interfaces that function as SPI's are
for instance the different sitemap component interfaces: Transformer,
ProcessingPipeline, Reader, Matcher, etc. An example of an API level
interface is for instance Processor and the different environment
related interfaces: Request, Context, Environment, etc.
--
Unico
Re: [Vote] Marking internal classes
Posted by Sylvain Wallez <sy...@apache.org>.
Unico Hommes wrote:
> Reinhard Poetz wrote:
<snip/>
>> I also propose to separate the cocoon.jar into two parts: One that
>> contains all interfaces that can be implemented and all classes that
>> can be used or extended and a second jar that contains the rest which
>> is only used internally. After migrating to Suversion this can be
>> done without breaking the history because this will also require some
>> file moving. IMO this step is necessary to separate our blocks from
>> Cocoon core, isn't it?
>
Good idea, but IMO this complements marking the classes, as if you load
the full Cocoon in an Eclipse project, completion will show all classes.
A notice at the beginning of the javadoc helps in noticing that you use
something that's forbidden.
> I like this too. There could be more than two parts though. There is
> the API part that contains interfaces used to embed cocoon into a
> certain environment. The SPI interfaces developers implement to extend
> the functionality of Cocoon. The different API implementations that we
> have (CLI, Servlet). And finally the core components.
Can you elaborate on the difference between API and SPI?
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Separation of cocoon.jar into smaller pieces
Posted by Reinhard Poetz <re...@apache.org>.
Unico Hommes wrote:
> Reinhard Poetz wrote:
>
>> I also propose to separate the cocoon.jar into two parts: One that
>> contains all interfaces that can be implemented and all classes that
>> can be used or extended and a second jar that contains the rest which
>> is only used internally. After migrating to Suversion this can be
>> done without breaking the history because this will also require some
>> file moving. IMO this step is necessary to separate our blocks from
>> Cocoon core, isn't it?
>>
>
> I like this too. There could be more than two parts though. There is
> the API part that contains interfaces used to embed cocoon into a
> certain environment. The SPI interfaces developers implement to extend
> the functionality of Cocoon. The different API implementations that we
> have (CLI, Servlet). And finally the core components.
Sounds fine. Any other thoughts?
As soon as we have migrated to Subversion I will prepare a proposal.
What's the current status of the migration process?
--
Reinhard
Re: [Vote] Marking internal classes
Posted by Unico Hommes <un...@hippo.nl>.
Reinhard Poetz wrote:
> Guido Casper wrote:
>
>> Guido Casper wrote:
>>
>>> Vadim Gritsenko wrote:
>>>
>>>> In all other situations, Carsten is right - this might cause
>>>> backward incompatibility. This is important for user-facing
>>>> classes. Should we start marking classes as internal, like
>>>> "<b>INTERNAL!!!</b>" in javadoc or some such?
>>>
>>>
>>>
>>>
>>> What about introducing @cocoon.usage tags I proposed a while ago like:
>>> @cocoon.usage published
>>>
>>> or:
>>> @cocoon.usage flowscript
>>>
>>> etc.
>>>
>>> This might someday also be used to generate separate Javadocs for
>>> different APIs.
>>
>>
>>
>> Hm, noone (but me :-) seems to like the idea.
>
>
>
> ;-)
>
>> So maybe it's a good idea to first have a quick vote about whether to
>> mark internal classes as such or to mark "published
>> classes/interfaces" as such (and then decide how to mark them).
>
>
>
> +1
>
> I also propose to separate the cocoon.jar into two parts: One that
> contains all interfaces that can be implemented and all classes that
> can be used or extended and a second jar that contains the rest which
> is only used internally. After migrating to Suversion this can be done
> without breaking the history because this will also require some file
> moving. IMO this step is necessary to separate our blocks from Cocoon
> core, isn't it?
>
I like this too. There could be more than two parts though. There is the
API part that contains interfaces used to embed cocoon into a certain
environment. The SPI interfaces developers implement to extend the
functionality of Cocoon. The different API implementations that we have
(CLI, Servlet). And finally the core components.
--
Unico
Re: [Vote] Marking internal classes
Posted by Reinhard Poetz <re...@apache.org>.
Guido Casper wrote:
> Guido Casper wrote:
>
>> Vadim Gritsenko wrote:
>>
>>> In all other situations, Carsten is right - this might cause
>>> backward incompatibility. This is important for user-facing classes.
>>> Should we start marking classes as internal, like
>>> "<b>INTERNAL!!!</b>" in javadoc or some such?
>>
>>
>>
>> What about introducing @cocoon.usage tags I proposed a while ago like:
>> @cocoon.usage published
>>
>> or:
>> @cocoon.usage flowscript
>>
>> etc.
>>
>> This might someday also be used to generate separate Javadocs for
>> different APIs.
>
>
> Hm, noone (but me :-) seems to like the idea.
;-)
> So maybe it's a good idea to first have a quick vote about whether to
> mark internal classes as such or to mark "published
> classes/interfaces" as such (and then decide how to mark them).
+1
I also propose to separate the cocoon.jar into two parts: One that
contains all interfaces that can be implemented and all classes that can
be used or extended and a second jar that contains the rest which is
only used internally. After migrating to Suversion this can be done
without breaking the history because this will also require some file
moving. IMO this step is necessary to separate our blocks from Cocoon
core, isn't it?
--
Reinhard
RE: [Vote] Marking internal classes
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Guido Casper wrote:
>
> Hm, noone (but me :-) seems to like the idea.
>
See it more positive, noone is against your idea!
> So maybe it's a good idea to first have a quick vote about
> whether to mark internal classes as such or to mark
> "published classes/interfaces"
> as such (and then decide how to mark them).
>
+1 for marking internal classes; everything that's not marked is
public.
Carsten
[Vote] Marking internal classes
Posted by Guido Casper <gc...@s-und-n.de>.
Guido Casper wrote:
> Vadim Gritsenko wrote:
>
>> In all other situations, Carsten is right - this might cause backward
>> incompatibility. This is important for user-facing classes. Should we
>> start marking classes as internal, like "<b>INTERNAL!!!</b>" in
>> javadoc or some such?
>
>
> What about introducing @cocoon.usage tags I proposed a while ago like:
> @cocoon.usage published
>
> or:
> @cocoon.usage flowscript
>
> etc.
>
> This might someday also be used to generate separate Javadocs for
> different APIs.
Hm, noone (but me :-) seems to like the idea.
So maybe it's a good idea to first have a quick vote about whether to
mark internal classes as such or to mark "published classes/interfaces"
as such (and then decide how to mark them).
Guido
Re: Clean up exception not throwed in some methods over the code.
Posted by Guido Casper <gc...@s-und-n.de>.
Vadim Gritsenko wrote:
> In all other situations, Carsten is right - this might cause backward
> incompatibility. This is important for user-facing classes. Should we
> start marking classes as internal, like "<b>INTERNAL!!!</b>" in javadoc
> or some such?
What about introducing @cocoon.usage tags I proposed a while ago like:
@cocoon.usage published
or:
@cocoon.usage flowscript
etc.
This might someday also be used to generate separate Javadocs for
different APIs.
Guido
Re: Clean up exception not throwed in some methods over the code.
Posted by Vadim Gritsenko <va...@reverycodes.com>.
Carsten Ziegeler wrote:
>Antonio Gallardo wrote:
>
>
>>Antonio Gallardo dijo:
>>
>>
>>>Hi:
>>>
>>>I also have another question. We have some exceptions that are not
>>>being throw at all, but the method declare it. Sample at line 76:
>>>
>>>
>>Filling the missing link :(
>>
>>http://cvs.apache.org/viewcvs.cgi/cocoon-2.1/src/blocks/xsp/ja
>>va/org/apache/cocoon/components/language/markup/Logicsheet.jav
>>a?annotate=1.3
>>
>>
>>>The constructor does not throw any of the declared Exceptions.
>>>
>>>Can we clean up this code? There are cca 150 similar places
>>>
>>>
>>over the code.
>>
>>
>In general I'm +1 for such changes, but unfortunately these are incompatible
>changes! For example, if a client has a try/catch clause for such
>an exception and you remove it from the list, then the client code
>is not compilable anymore as the exception is not thrown inside
>the block anymore.
>So, I would say, let's leave them there (but I'm not opposed to remove them
>:) ).
>
>
"Throws" declarations can be safely removed in the situation when method
implements an interface. Interface will have exception declarations, and
interface implementation might not have them if it does not need them.
In all other situations, Carsten is right - this might cause backward
incompatibility. This is important for user-facing classes. Should we
start marking classes as internal, like "<b>INTERNAL!!!</b>" in javadoc
or some such?
Vadim
RE: Clean up exception not throwed in some methods over the code.
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Antonio Gallardo wrote:
>
> Antonio Gallardo dijo:
> > Hi:
> >
> > I also have another question. We have some exceptions that are not
> > being throw at all, but the method declare it. Sample at line 76:
>
> Filling the missing link :(
>
> http://cvs.apache.org/viewcvs.cgi/cocoon-2.1/src/blocks/xsp/ja
> va/org/apache/cocoon/components/language/markup/Logicsheet.jav
> a?annotate=1.3
> >
> > The constructor does not throw any of the declared Exceptions.
> >
> > Can we clean up this code? There are cca 150 similar places
> over the code.
> >
In general I'm +1 for such changes, but unfortunately these are incompatible
changes! For example, if a client has a try/catch clause for such
an exception and you remove it from the list, then the client code
is not compilable anymore as the exception is not thrown inside
the block anymore.
So, I would say, let's leave them there (but I'm not opposed to remove them
:) ).
Carsten
Re: Clean up exception not throwed in some methods over the code.
Posted by Antonio Gallardo <ag...@agssa.net>.
Antonio Gallardo dijo:
> Hi:
>
> I also have another question. We have some exceptions that are not being
> throw at all, but the method declare it. Sample at line 76:
Filling the missing link :(
http://cvs.apache.org/viewcvs.cgi/cocoon-2.1/src/blocks/xsp/java/org/apache/cocoon/components/language/markup/Logicsheet.java?annotate=1.3
>
> The constructor does not throw any of the declared Exceptions.
>
> Can we clean up this code? There are cca 150 similar places over the code.
>
Best Regards,
Antonio Gallardo