[CLI] Breaking CocoonBean Interface

[Upayavira <uv...@upaya.co.uk>]

Dear All,

As my first commit, I want to post some changes to the CLI that I've had waiting 
for some time. Before doing so, I wanted to make sure that these do not cause 
any problems, as they break the current interface of the CocoonBean.

Please let me know if there is any reason why I shouldn't commit this. If I don't 
hear any, I'll just get on and do it.

The changes include:
1) Improved broken link handling
   Specify whether or not a broken link file should be generated
   Specify whether the broken link file should be plain text or XML
   Specify whether a file should be generated for a broken link
   Specify whether this generated file should have an extension appended
   None of this breaks any interfaces, so it should be non-contentious
   Default behaviour is as before
2) Replaced Destination interface with ModifiableSources

If you use a URI file, or provide the URI to spider via a command line argument, 
behaviour should remain the same (i.e. specify a destination folder and one or 
more Cocoon URIs to generate).

If you use the xconf file, you have new options (old behaviour still works). These 
all relate to how the final file's URI is built up from the generated page's URI and 
the specified destination URI.

   <!-- The old behaviour - appends uri to the specified destination directory -->
   <uri>documents/index.html</uri>

   <!-- Append: append the generated page's URI to the end of the source URI. -->
   <uri type="append" src-prefix="documents/" src="index.html" dest="build/dest/"/>

   <-- Replace: Completely ignore the generated page's URI - just use the 
destination URI -->
   <uri type="replace" src-prefix="documents/" src="index.html" 
dest="build/dest/docs.html"/>

   <!-- Insert: Insert generated page's URI into the destination URI at the point 
marked with a * (example uses fictional zip protocol) -->
   <uri type="insert" src-prefix="documents/" src="index.html" 
dest="zip://*.zip/page.html"/>

It is this that breaks the interface to the CocoonBean. Now, instead of passing a 
Map of destinations, or a single destination, you call addTarget(). There are a 
number of versions of this method, with increasing functionality:

CocoonBean cocoon = new CocoonBean();

// Functionality most like before:
cocoon.setDestDir("built/dest/");
cocoon.addTarget("documents/index.html");

// Another way of achieving the same (allows multiple targets to use different
// destination directories)
cocoon.addTarget("documents/index.html", "build/dest/");

// Allows you to specify a prefix for the source URI, which is excluded from the 
// URI of the final generated file
cocoon.addTarget("documents/", "index.html", "build/dest/");

// Allows you to specify all the above, including a method for creating the 
// destination URI from the generated page's URI and the specified destination
// URI
cocoon.addTarget("append", "documents/", "index.html", "build/dest");

In any of the above that specify a destination URI, you can use any URI that is 
Modifiable, such as FTP, XML databases, CVS repositories, etc.

One of my next tasks is a VFS source, giving access to some nice new 
ModifiableSources.

I'll update the Wiki (with a new 2.1 doc and a CocoonBean page too) soon.

I hope you all like it.

Regards, Upayavira

Re: [CLI] Breaking CocoonBean Interface

[Vadim Gritsenko <va...@verizon.net>]

Upayavira wrote:

>>>It is only mentioned along with the <dest-dir> node in the cli.xconf.
>>>If I removed that option in the xconf file, setDestDir would go
>>>easily.
>>>
>>>      
>>>
>>No; you don't need to remove the option, and you don't need to change
>>config file at all. Do you want me to show you how? :)
>>    
>>
>
>Go for it!
>

Done. Please verify that all is all right. "build docs" still works 
which is a good sign ;-)

Vadim

Re: [CLI] Breaking CocoonBean Interface

[Upayavira <uv...@upaya.co.uk>]

> >It is only mentioned along with the <dest-dir> node in the cli.xconf.
> >If I removed that option in the xconf file, setDestDir would go
> >easily.
> >
> 
> No; you don't need to remove the option, and you don't need to change
> config file at all. Do you want me to show you how? :)

Go for it!

Upayavira

Re: [CLI] Breaking CocoonBean Interface

[Vadim Gritsenko <va...@verizon.net>]

Upayavira wrote:

>Vadim,
>
>  
>
>>>>>It is particularly the removal of the Destination interface that
>>>>>breaks the interface. However, removing the setDestDir will
>>>>>certainly make a cleaner interface. I'll do that.
>>>>>          
>>>>>
>
>  
>
>>>I didn't remove it in the end, because it would have taken quite a
>>>bit of plumbing to work around its non-presence (in order to at least
>>>keep the CLI interface the same). 
>>>      
>>>
>
>  
>
>>Hm... I found only one place to be changed in Main.java. Line 481,
>>need to pass destDir. Otherwise, there is no major changes in CLI.
>>    
>>
>
>It is only mentioned along with the <dest-dir> node in the cli.xconf. If 
>I removed that option in the xconf file, setDestDir would go easily.
>

No; you don't need to remove the option, and you don't need to change 
config file at all. Do you want me to show you how? :)

Vadim

Re: [CLI] Breaking CocoonBean Interface

[Upayavira <uv...@upaya.co.uk>]

Vadim,

> >>>It is particularly the removal of the Destination interface that
> >>>breaks the interface. However, removing the setDestDir will
> >>>certainly make a cleaner interface. I'll do that.

> >I didn't remove it in the end, because it would have taken quite a
> >bit of plumbing to work around its non-presence (in order to at least
> >keep the CLI interface the same). 

> Hm... I found only one place to be changed in Main.java. Line 481,
> need to pass destDir. Otherwise, there is no major changes in CLI.

It is only mentioned along with the <dest-dir> node in the cli.xconf. If 
I removed that option in the xconf file, setDestDir would go easily.

However, that would require the user to specify the destination for 
every uri in the xconf file. Is that okay, or should I provide another
way to provide a catch all destination, e.g:

<uris dest="build/dest">
  <uri src="xxxx"/>
</uris>

> And one more thing... CocoonBean.java, line 166: error text does not
> make much sense in Bean context (what is "-d"? :), this text is
> appropriate in Main.java. 

Yup. Should be an exception and Main reports it.

> And System.exit should be replaced with
> exception, I guess you already know this.

Eventually. 

Thanks, Upayavira

Re: [CLI] Breaking CocoonBean Interface

[Vadim Gritsenko <va...@verizon.net>]

Upayavira wrote:

>On 4 Jun 2003 at 23:22, Vadim Gritsenko wrote:
>
>  
>
>>>It is particularly the removal of the Destination interface that
>>>breaks the interface. However, removing the setDestDir will certainly
>>>make a cleaner interface. I'll do that.
>>>      
>>>
>>Thanks. Sorry for me being slow.
>>    
>>
>
>Slow to reply, or slow to understand? ;-)
>
>I didn't remove it in the end, because it would have taken quite a bit of plumbing to 
>work around its non-presence (in order to at least keep the CLI interface the same). 
>

Hm... I found only one place to be changed in Main.java. Line 481, need 
to pass destDir. Otherwise, there is no major changes in CLI.


>Perhaps I should deprecate it and remove it later?
>

It's not the best idea because this class was just recently created. 
It's better either to leave it alone or remove.

And one more thing... CocoonBean.java, line 166: error text does not 
make much sense in Bean context (what is "-d"? :), this text is 
appropriate in Main.java. And System.exit should be replaced with 
exception, I guess you already know this.

Vadim

Re: [CLI] Breaking CocoonBean Interface

[Upayavira <uv...@upaya.co.uk>]

On 4 Jun 2003 at 23:22, Vadim Gritsenko wrote:

> >It is particularly the removal of the Destination interface that
> >breaks the interface. However, removing the setDestDir will certainly
> >make a cleaner interface. I'll do that.
> 
> Thanks. Sorry for me being slow.

Slow to reply, or slow to understand? ;-)

I didn't remove it in the end, because it would have taken quite a bit of plumbing to 
work around its non-presence (in order to at least keep the CLI interface the same). 
Perhaps I should deprecate it and remove it later?

Thanks again.

Upayavira

Re: [CLI] Breaking CocoonBean Interface

[Vadim Gritsenko <va...@verizon.net>]

Upayavira wrote:
...

>It is particularly the removal of the Destination interface that breaks the interface. 
>However, removing the setDestDir will certainly make a cleaner interface. I'll do that.
>  
>

Thanks. Sorry for me being slow.

Vadim

Re: [CLI] Breaking CocoonBean Interface

[Upayavira <uv...@upaya.co.uk>]

Vadim,

...
> >   <uri type="append" src-prefix="documents/" src="index.html"
> >   dest="build/dest/"/> <uri type="replace" src-prefix="documents/"
> >   src="index.html" 
> >dest="build/dest/docs.html"/>
> >   <uri type="insert" src-prefix="documents/" src="index.html" 
> >dest="zip://*.zip/page.html"/>
> 
> It took me some time to understand meaning of "append", "replace",
> "insert". Can we choose some other names for this, and/or combine
> append and replace types together? (What would happen in "replace"
> type while processing more than one page?) Also, what goes instead of
> '*' in "insert"?

Append sticks the uri of the generated page onto the end of the dest uri.
Replace just uses the dest uri, ignoring the uri of the generated page.
Insert lets you put the uri of the generated page into the middle of the dest uri.

Is that any clearer?

I can't see how they can be merged, as they do very different things. However, I'm 
quite open to better names, although I suspect that better explanations might work 
just as well. When posted, I'll publish docs on the Wiki. I'm happy to create xdocs too, 
if you can point me in the right direction.

> And one more question... Can you remind me why src-prefix attribute is
> necessary? My guess is that it specifies "base" directory, and no
> crawling happens above it. If my guess is right, attribute can be
> named "src-base"...

The src-prefix is the part of the uri of the generated page that isn't used when building 
the destination uri. So if you have src-prefix="documents/" and src="index.html" and 
dest="site/", your final uri would be "site/index.html". 

If you skipped the src-prefix, you'd need src="documents/index.html" instead, which 
would result in "site/documents/index.html". It will then be impossible to get rid of the 
'documents' from the URI without creating an entirely new webapp.

> >It is this that breaks the interface to the CocoonBean. Now, instead
> >of passing a Map of destinations, or a single destination, you call
> >addTarget(). There are a number of versions of this method, with
> >increasing functionality:
> >
> >CocoonBean cocoon = new CocoonBean();
> >
> >// Functionality most like before:
> >cocoon.setDestDir("built/dest/");
> >
> 
> CocoonBean was introduced just recently and we had no single beta
> release yet, so I think it's ok to break this interface. If method
> setDestDir is not necessary anymore, feel free to remove it.

It is particularly the removal of the Destination interface that breaks the interface. 
However, removing the setDestDir will certainly make a cleaner interface. I'll do that.

Thanks for your comments.

Upayavira

Re: [CLI] Breaking CocoonBean Interface

[Vadim Gritsenko <va...@verizon.net>]

Upayavira wrote:

>Dear All,
>  
>
...

>The changes include:
>1) Improved broken link handling
>2) Replaced Destination interface with ModifiableSources
>  
>
...

>   <uri type="append" src-prefix="documents/" src="index.html" dest="build/dest/"/>
>   <uri type="replace" src-prefix="documents/" src="index.html" 
>dest="build/dest/docs.html"/>
>   <uri type="insert" src-prefix="documents/" src="index.html" 
>dest="zip://*.zip/page.html"/>
>

It took me some time to understand meaning of "append", "replace", 
"insert". Can we choose some other names for this, and/or combine append 
and replace types together? (What would happen in "replace" type while 
processing more than one page?) Also, what goes instead of '*' in "insert"?

And one more question... Can you remind me why src-prefix attribute is 
necessary? My guess is that it specifies "base" directory, and no 
crawling happens above it. If my guess is right, attribute can be named 
"src-base"...


>It is this that breaks the interface to the CocoonBean. Now, instead of passing a 
>Map of destinations, or a single destination, you call addTarget(). There are a 
>number of versions of this method, with increasing functionality:
>
>CocoonBean cocoon = new CocoonBean();
>
>// Functionality most like before:
>cocoon.setDestDir("built/dest/");
>

CocoonBean was introduced just recently and we had no single beta 
release yet, so I think it's ok to break this interface. If method 
setDestDir is not necessary anymore, feel free to remove it.


Vadim