Polishing the flow contracts

[Stefano Mazzocchi <st...@apache.org>]

One of the major release showstoppers is the lack of confidence on the 
flow contracts.

We cannot release the flow without being confident about its contracts.

And it has been decided to ship the flow with Cocoon 2.1.

So, in order to release, we have to finish polishing the flow.

Things to do are:

1) cleaning up the proper hooks between the flow and the cocoon 
internal. This means adding a flow native object to the Object Model so 
that all cocoon components can have access to it directly (this will 
remove the need for two different velocity generators)

Vadim and Sylvain identified a clean solution for this, can you guys 
please refresh those concepts?

2) polishing the FOM.

                                      - o -

Here is what I would like to see:

  1) no functions without an object namespace. This is to imply that all 
non-prefixed functions belong to the flow. Provides coherent cognitive 
context.

  2) no function duplication. There is only one function that does 
something. [of course, javascript allows you to change those function 
names with your flow, but that's up to the user and doesn't influence 
our contracts[

  3) the following objects:

     flow
     cocoon
     continuation
     log

  4) the following functions

Flow Object:
     flow.import() -> imports another flowscript

Cocoon Object:
     cocoon.sendPage(uri, dict) -> sends a pipeline to the client

     cocoon.sendPageAndWait(uri, dict) -> sends a pipeline to the client 
and save the continuation.

     cocoon.process(uri, dict, output

Re: Polishing the flow contracts

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

> One of the big changes of Cocoon 2.1 compared to 2.0 is that 
> SourceResolver is now available as a regular component, meaning you
> get it using "cocoon.manager.lookup(SourceResolver.ROLE)", so I don't
> see the need to expose it as a property.
> 
> Moreover the process() function could simply take an URI string and
> let the underlying implementation use the SourceResolver to get the
> actual source and verify that it's writeable.
> 
> You will then write :
> cocoon.process("whatever", "file://blah") but also
> cocoon.process("whatever", "context://xdocs/content/foo.xml") (for a
> deployed webapp) and even cocoon.process("whatever",
> "cvs://my-module/foo")
> 
> How does it sound ?

Sounds even better to me.

Upayavira

Re: Polishing the flow contracts

[Pier Fumagalli <pi...@betaversion.org>]

"Sylvain Wallez" <sy...@anyware-tech.com> wrote:

> Moreover the process() function could simply take an URI string and let
> the underlying implementation use the SourceResolver to get the actual
> source and verify that it's writeable.
> 
> You will then write :
> cocoon.process("whatever", "file://blah") but also
> cocoon.process("whatever", "context://xdocs/content/foo.xml") (for a
> deployed webapp) and even
> cocoon.process("whatever", "cvs://my-module/foo")
> 
> How does it sound ?

I prefer this approach to exposing the source resolver itself, indeed...

If one, then, needs to get a hold on the resolver, yes, he can obtain an
instance of the resolver through the component manager...

    Pier

Re: Polishing the flow contracts

[Sylvain Wallez <sy...@anyware-tech.com>]

Stefano Mazzocchi wrote:

> Pier Fumagalli wrote:
>
>> "Upayavira" <uv...@upaya.co.uk> wrote:
>>
>>
>>>>  var source = cocoon.componentManager.get(
>>>>     Packages.org.apache.excalibur.source.WriteableSource.ROLE +
>>>>     "/file
>>>>  );
>>>>  source.setDest("whatever");
>>>>  cocoon.process("whatever",source);
>>>
>>>
>>> FWIW, that fits nicely with what I'm thinking of doing on the CLI. I 
>>> plan to
>>> make it write to sources rather than files, and a 
>>> cocoon.process("some-uri", source)
>>> would work well.
>>>
>>> More on my ideas soon.
>>>
>>> On the subject of the flow, presumably you could expose the source 
>>> resolver,
>>> so that you could write the above with something like:
>>>
>>> cocoon.process("whatever", resolver.getSource("file://blah"));
>>
>>
>>
>> It's quite odd to "write" to a "source", but well, better than using
>> LiveConnect.
>>
>> Thinking out loud... Should the "resolver" then be another read-only
>> attribute of the script (instead of passing through the component 
>> manager?)
>
>
> I think it would make sense.
>
> anybody sees a reason not to do this? 


One of the big changes of Cocoon 2.1 compared to 2.0 is that 
SourceResolver is now available as a regular component, meaning you get 
it using "cocoon.manager.lookup(SourceResolver.ROLE)", so I don't see 
the need to expose it as a property.

Moreover the process() function could simply take an URI string and let 
the underlying implementation use the SourceResolver to get the actual 
source and verify that it's writeable.

You will then write :
cocoon.process("whatever", "file://blah") but also
cocoon.process("whatever", "context://xdocs/content/foo.xml") (for a 
deployed webapp) and even
cocoon.process("whatever", "cvs://my-module/foo")

How does it sound ?

Sylvain

-- 
Sylvain Wallez                                  Anyware Technologies
http://www.apache.org/~sylvain           http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }

Re: Polishing the flow contracts

[Stefano Mazzocchi <st...@apache.org>]

Pier Fumagalli wrote:
> "Upayavira" <uv...@upaya.co.uk> wrote:
> 
> 
>>>  var source = cocoon.componentManager.get(
>>>     Packages.org.apache.excalibur.source.WriteableSource.ROLE +
>>>     "/file
>>>  );
>>>  source.setDest("whatever");
>>>  cocoon.process("whatever",source);
>>
>>FWIW, that fits nicely with what I'm thinking of doing on the CLI. I plan to
>>make it 
>>write to sources rather than files, and a cocoon.process("some-uri", source)
>>would 
>>work well.
>>
>>More on my ideas soon.
>>
>>On the subject of the flow, presumably you could expose the source resolver,
>>so that 
>>you could write the above with something like:
>>
>>cocoon.process("whatever", resolver.getSource("file://blah"));
> 
> 
> It's quite odd to "write" to a "source", but well, better than using
> LiveConnect.
> 
> Thinking out loud... Should the "resolver" then be another read-only
> attribute of the script (instead of passing through the component manager?)

I think it would make sense.

anybody sees a reason not to do this?

Stefano.

Re: Polishing the flow contracts

[Pier Fumagalli <pi...@betaversion.org>]

"Upayavira" <uv...@upaya.co.uk> wrote:

>>   var source = cocoon.componentManager.get(
>>      Packages.org.apache.excalibur.source.WriteableSource.ROLE +
>>      "/file
>>   );
>>   source.setDest("whatever");
>>   cocoon.process("whatever",source);
> 
> FWIW, that fits nicely with what I'm thinking of doing on the CLI. I plan to
> make it 
> write to sources rather than files, and a cocoon.process("some-uri", source)
> would 
> work well.
> 
> More on my ideas soon.
> 
> On the subject of the flow, presumably you could expose the source resolver,
> so that 
> you could write the above with something like:
> 
> cocoon.process("whatever", resolver.getSource("file://blah"));

It's quite odd to "write" to a "source", but well, better than using
LiveConnect.

Thinking out loud... Should the "resolver" then be another read-only
attribute of the script (instead of passing through the component manager?)

    Pier

Re: Polishing the flow contracts

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

>   var source = cocoon.componentManager.get(
>      Packages.org.apache.excalibur.source.WriteableSource.ROLE +
>      "/file
>   );
>   source.setDest("whatever");
>   cocoon.process("whatever",source);

FWIW, that fits nicely with what I'm thinking of doing on the CLI. I plan to make it 
write to sources rather than files, and a cocoon.process("some-uri", source) would 
work well.

More on my ideas soon.

On the subject of the flow, presumably you could expose the source resolver, so that 
you could write the above with something like:

cocoon.process("whatever", resolver.getSource("file://blah"));

Regards, Upayavira

Re: Polishing the flow contracts

[Stefano Mazzocchi <st...@apache.org>]

Pier Fumagalli wrote:
> On 30/3/03 14:43, "Stefano Mazzocchi" <st...@apache.org> wrote:
> 
> 
>>Cocoon Object:
>>[...]
>>   cocoon.process(uri, dict, output
> 
> 
> There's another thing I don't really like (and being the implementor of the
> feature, yes, it's my own fault)...
> 
> Currently to the "process" method we ought to pass a nice OutputStream
> instance, which we can create using the Rhino extensions to acess Java
> objects.
> 
> Now, I'd rather like to see it more "factored" out, a some sort of
> "OutputStreamFactory", like we do for source files...
> 
> Anyone has some design hints on how we could achieve that? Anyone else sees
> it as I do as a "design hack" ???

I used it yesterday and I agree with you. Using LiveConnect (the 
javascript/java connector) for such a thing smells of hacky.

We already have the concept of WriteableSources and I think the Source 
selector is already available thru the cocoon.componentManager.

But you would trade

  process ("whatever",{},new java.io.FileOutputStream(file));

for something like (sorry for the formatting and the pseudo-code)

  var source = cocoon.componentManager.get(
     Packages.org.apache.excalibur.source.WriteableSource.ROLE + "/file
  );
  source.setDest("whatever");
  cocoon.process("whatever",source);

which is for sure better but can't go along without LiveConnect.

there is one advantage thought: currently, there is no easy way to 
resolve a uri againts the servlet context real path. This abstraction 
could do such a thing transparently and enforce an inversion of control 
that would definately ease portability across platforms.

Thoughts?

Stefano.

Re: Polishing the flow contracts

[Pier Fumagalli <pi...@betaversion.org>]

On 30/3/03 14:43, "Stefano Mazzocchi" <st...@apache.org> wrote:

> Cocoon Object:
> [...]
>    cocoon.process(uri, dict, output

There's another thing I don't really like (and being the implementor of the
feature, yes, it's my own fault)...

Currently to the "process" method we ought to pass a nice OutputStream
instance, which we can create using the Rhino extensions to acess Java
objects.

Now, I'd rather like to see it more "factored" out, a some sort of
"OutputStreamFactory", like we do for source files...

Anyone has some design hints on how we could achieve that? Anyone else sees
it as I do as a "design hack" ???

    Pier (the culprit)

Re: Polishing the flow contracts

[Christopher Oliver <re...@verizon.net>]

Stefano Mazzocchi wrote:

>>>>> Flow Object:
>>>>>  flow.import() -> imports another flowscript 
>>>>

import is a JavaScript keyword. We can't use it as the name of a function

>>>>>
>>>> Hmmm... Should we allow cross-language (when/if we're going to have 
>>>> it)
>>>> flowscripts interaction? Because otherwise I'd prefer a name such as
>>>> "interpreter"....
>>>
>>>
>>> I don't get it. What's wrong with the name flow?
>>>
>> I think the same as Pier here, you merely don't include a flow, but
>> include or import another javascript file. Using flow here, I think,
>> leads the user to false assumption, that this is flow specific.
>> For instance using jruby or another great scripting language (jython,
>> ...), this would work somewhat different like Module::include in jruby
>> or import in jython.
>
>
> Ok, I agree with you people.
>
> I wonder, doesn't javascript have such a native facility for importing 
> external scripts? I would be surprised if it didn't.
>
It doesn't. It's up to the embedding how this is accomplished. Rhino and 
Spidermonkey (Mozilla engines) have "load()".

Regards,
Chris

Re: Polishing the flow contracts

[Stefano Mazzocchi <st...@apache.org>]

Jakob Praher wrote:
> Am Son, 2003-03-30 um 21.32 schrieb Stefano Mazzocchi:
> 
> 
> 
>>>>4) the following functions
>>>>
>>>>Flow Object:
>>>>  flow.import() -> imports another flowscript
>>>
> 
>> 
>>
>>>Hmmm... Should we allow cross-language (when/if we're going to have it)
>>>flowscripts interaction? Because otherwise I'd prefer a name such as
>>>"interpreter"....
>>
>>I don't get it. What's wrong with the name flow?
>>
> 
> 
> I think the same as Pier here, you merely don't include a flow, but
> include or import another javascript file. Using flow here, I think,
> leads the user to false assumption, that this is flow specific.
> For instance using jruby or another great scripting language (jython,
> ...), this would work somewhat different like Module::include in jruby
> or import in jython.

Ok, I agree with you people.

I wonder, doesn't javascript have such a native facility for importing 
external scripts? I would be surprised if it didn't.

Chris? (you are the javascript guru around here :)

Stefano.

Re: Polishing the flow contracts

[Jakob Praher <jp...@yahoo.de>]

Am Son, 2003-03-30 um 21.32 schrieb Stefano Mazzocchi:


> >>4) the following functions
> >>
> >>Flow Object:
> >>   flow.import() -> imports another flowscript
> >

>  
> > 
> > Hmmm... Should we allow cross-language (when/if we're going to have it)
> > flowscripts interaction? Because otherwise I'd prefer a name such as
> > "interpreter"....
> 
> I don't get it. What's wrong with the name flow?
> 

I think the same as Pier here, you merely don't include a flow, but
include or import another javascript file. Using flow here, I think,
leads the user to false assumption, that this is flow specific.
For instance using jruby or another great scripting language (jython,
...), this would work somewhat different like Module::include in jruby
or import in jython.


-- Jakob

Re: Polishing the flow contracts

[Pier Fumagalli <pi...@betaversion.org>]

"Stefano Mazzocchi" <st...@apache.org> wrote:

<skip reason="mutual agreement"/>

>> "Flow" in my mind is the whole kit and caboodles: it's the "Cocoon Flow", a
>> set of API to do something.
>> 
>> The "Flow" in my mind is made up by:
>> - "Cocoon", an interface to talk to the cocoon internals
>> - "Log" the logging facility
>> - "Interpreter" whatever executes our script
>> - Other objects (such as "Continuation") which instances we can get from the
>>   three above mentioned instances...
>> 
>> "Flow" is tha package (IDL module), "Interpreter" is the connection to the
>> scripting engine...
> 
> Yes, I see your point, but 'flow' in my mind is the instance of the
> entire concept that handles my flow. So
> 
> flow.import()
> 
> means that I'm adding another information to my flow. The fact that this
> flow is implemented with a javascript interpreter is, in fact, unimportant.
> 
> Suppose future allows us to write the flow directly in java and that a
> future JSR adds continuations as native objects in java: would it be
> sane to call
> 
> interpreter.import()
> 
> at that point?
> 
> Flow is totally abstracted already, as a concept, from the underlying
> implementation and the semantics of our FOM should keep suggesting that.

If I agree that the concept of "import" means "something that is being added
to my flow" wouldn't it make more sense to have "this.import()" ???

I import another source file into THIS object (my script).

(Just thinking out loud randomly as I really have a bad taste when saying
"flow.import()")

<offtopic>

>> Use Entourage or Apple Mail on your OS/X box! :-) :-) :-)
> 
> I'm sooooo used to mozmail shortcuts... and spam filtering works so well
> and you don't allow me to install spambayes on pulse! :(

Entourage does it as well...

> but there is hope: they are workign on a stripped-down version of
> mozmail to go along with phoenix/camino... hopefully with native widgets
> instead of that super-heavy XUL stuff.

That would be kute! :-)

> besides, I think it's not a problem with mozmail but my stupid router
> that cuts my connections... but hopefully I'm going to be out of here soon.

Don't tell me... Every time I look at netstat I see all your connections in
CLOSE_WAIT forever! :-)

</offtopic>

    Pier

Re: Polishing the flow contracts

[Stefano Mazzocchi <st...@apache.org>]

Pier Fumagalli wrote:
> On 30/3/03 20:32, "Stefano Mazzocchi" <st...@apache.org> wrote:
> 
> 
>>Pier Fumagalli wrote:
>>
>>>On 30/3/03 2:43 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
>>>
>>>
>>>
>>>>Here is what I would like to see:
>>>>
>>>>1) no functions without an object namespace. This is to imply that all
>>>>non-prefixed functions belong to the flow. Provides coherent cognitive
>>>>context.
>>>
>>>
>>>I don't understand that.... What do you mean by "function with(out) object
>>>namespace?
>>
>>I mean functions without an object up front.
>>
>>info() <- bad
>>log.info() <- good
> 
> 
> Ah... Ok, gotcha...
> 
> Now, you realize that "info()" can also be called as "this.info()", right?

right, but all my other flow methods are as well. what i want is to 
suggest a mental association between

  this./nothing -> your flow stuff

  cocoon/log -> our stuff

  * -> other objects that either you or flow blocks provide

> So, you are implying that you want the basic class of the "script" object
> not to expose any method, much like an empty interface...

Exactly.

> So, the only thing we should expose are 3 read only properties:
> 
> cocoon: an instance of Cocoon
> log: an instance of Log
> flow: an instance of Flow
> 

yes

>>>>4) the following functions
>>>>
>>>>Flow Object:
>>>>  flow.import() -> imports another flowscript
>>>
>>>
>>>Hmmm... Should we allow cross-language (when/if we're going to have it)
>>>flowscripts interaction? Because otherwise I'd prefer a name such as
>>>"interpreter"....
>>
>>I don't get it. What's wrong with the name flow?
> 
> 
> "Flow" in my mind is the whole kit and caboodles: it's the "Cocoon Flow", a
> set of API to do something.
> 
> The "Flow" in my mind is made up by:
> - "Cocoon", an interface to talk to the cocoon internals
> - "Log" the logging facility
> - "Interpreter" whatever executes our script
> - Other objects (such as "Continuation") which instances we can get from the
>   three above mentioned instances...
> 
> "Flow" is tha package (IDL module), "Interpreter" is the connection to the
> scripting engine...

Yes, I see your point, but 'flow' in my mind is the instance of the 
entire concept that handles my flow. So

  flow.import()

means that I'm adding another information to my flow. The fact that this 
flow is implemented with a javascript interpreter is, in fact, unimportant.

Suppose future allows us to write the flow directly in java and that a 
future JSR adds continuations as native objects in java: would it be 
sane to call

  interpreter.import()

at that point?

Flow is totally abstracted already, as a concept, from the underlying 
implementation and the semantics of our FOM should keep suggesting that.

> 
>>>>Cocoon Object:
>>>>  cocoon.sendPage(uri, dict) -> sends a pipeline to the client
>>>>
>>>>  cocoon.sendPageAndWait(uri, dict) -> sends a pipeline to the client
>>>>and save the continuation.
>>>>
>>>>  cocoon.process(uri, dict, output
>>>
>>>
>>>Stefano... This one was cut as well... Can you please forward the rest????
>>
>>Oh, #$&*! No, i can't, that message wasn't stored in my sent folder :/
>>
>>grrrr
>>
>>I hate these things.
> 
> 
> Use Entourage or Apple Mail on your OS/X box! :-) :-) :-)

I'm sooooo used to mozmail shortcuts... and spam filtering works so well 
and you don't allow me to install spambayes on pulse! :(

but there is hope: they are workign on a stripped-down version of 
mozmail to go along with phoenix/camino... hopefully with native widgets 
instead of that super-heavy XUL stuff.

besides, I think it's not a problem with mozmail but my stupid router 
that cuts my connections... but hopefully I'm going to be out of here soon.

Stefano.

Re: Polishing the flow contracts

[Pier Fumagalli <pi...@betaversion.org>]

On 30/3/03 20:32, "Stefano Mazzocchi" <st...@apache.org> wrote:

> Pier Fumagalli wrote:
>> On 30/3/03 2:43 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
>> 
>> 
>>> Here is what I would like to see:
>>> 
>>> 1) no functions without an object namespace. This is to imply that all
>>> non-prefixed functions belong to the flow. Provides coherent cognitive
>>> context.
>> 
>> 
>> I don't understand that.... What do you mean by "function with(out) object
>> namespace?
> 
> I mean functions without an object up front.
> 
> info() <- bad
> log.info() <- good

Ah... Ok, gotcha...

Now, you realize that "info()" can also be called as "this.info()", right?
So, you are implying that you want the basic class of the "script" object
not to expose any method, much like an empty interface...

So, the only thing we should expose are 3 read only properties:

cocoon: an instance of Cocoon
log: an instance of Log
flow: an instance of Flow

>>> 4) the following functions
>>> 
>>> Flow Object:
>>>   flow.import() -> imports another flowscript
>> 
>> 
>> Hmmm... Should we allow cross-language (when/if we're going to have it)
>> flowscripts interaction? Because otherwise I'd prefer a name such as
>> "interpreter"....
> 
> I don't get it. What's wrong with the name flow?

"Flow" in my mind is the whole kit and caboodles: it's the "Cocoon Flow", a
set of API to do something.

The "Flow" in my mind is made up by:
- "Cocoon", an interface to talk to the cocoon internals
- "Log" the logging facility
- "Interpreter" whatever executes our script
- Other objects (such as "Continuation") which instances we can get from the
  three above mentioned instances...

"Flow" is tha package (IDL module), "Interpreter" is the connection to the
scripting engine...

>>> Cocoon Object:
>>>   cocoon.sendPage(uri, dict) -> sends a pipeline to the client
>>> 
>>>   cocoon.sendPageAndWait(uri, dict) -> sends a pipeline to the client
>>> and save the continuation.
>>> 
>>>   cocoon.process(uri, dict, output
>> 
>> 
>> Stefano... This one was cut as well... Can you please forward the rest????
> 
> Oh, #$&*! No, i can't, that message wasn't stored in my sent folder :/
> 
> grrrr
> 
> I hate these things.

Use Entourage or Apple Mail on your OS/X box! :-) :-) :-)

    Pier

Re: Polishing the flow contracts

[Stefano Mazzocchi <st...@apache.org>]

Pier Fumagalli wrote:
> On 30/3/03 2:43 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
> 
> 
>>Here is what I would like to see:
>>
>>1) no functions without an object namespace. This is to imply that all
>>non-prefixed functions belong to the flow. Provides coherent cognitive
>>context.
> 
> 
> I don't understand that.... What do you mean by "function with(out) object
> namespace?

I mean functions without an object up front.

info() <- bad
log.info() <- good

>>4) the following functions
>>
>>Flow Object:
>>   flow.import() -> imports another flowscript
> 
> 
> Hmmm... Should we allow cross-language (when/if we're going to have it)
> flowscripts interaction? Because otherwise I'd prefer a name such as
> "interpreter"....

I don't get it. What's wrong with the name flow?

>>Cocoon Object:
>>   cocoon.sendPage(uri, dict) -> sends a pipeline to the client
>>
>>   cocoon.sendPageAndWait(uri, dict) -> sends a pipeline to the client
>>and save the continuation.
>>
>>   cocoon.process(uri, dict, output
> 
> 
> Stefano... This one was cut as well... Can you please forward the rest????

Oh, #$&*! No, i can't, that message wasn't stored in my sent folder :/

grrrr

I hate these things.

Stefano.

Re: Polishing the flow contracts

[Pier Fumagalli <pi...@betaversion.org>]

On 30/3/03 2:43 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:

> Here is what I would like to see:
> 
> 1) no functions without an object namespace. This is to imply that all
> non-prefixed functions belong to the flow. Provides coherent cognitive
> context.

I don't understand that.... What do you mean by "function with(out) object
namespace?

> 4) the following functions
> 
> Flow Object:
>    flow.import() -> imports another flowscript

Hmmm... Should we allow cross-language (when/if we're going to have it)
flowscripts interaction? Because otherwise I'd prefer a name such as
"interpreter"....

> Cocoon Object:
>    cocoon.sendPage(uri, dict) -> sends a pipeline to the client
> 
>    cocoon.sendPageAndWait(uri, dict) -> sends a pipeline to the client
> and save the continuation.
> 
>    cocoon.process(uri, dict, output

Stefano... This one was cut as well... Can you please forward the rest????

    Pier