cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Unico Hommes <un...@hippo.nl>
Subject Re: [Vote] Marking internal classes
Date Mon, 19 Jul 2004 13:47:43 GMT
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

Mime
View raw message