Groovy docs ready for review

[Tim Fox]

I've completed the Groovy API docs and tutorial.

Would any Groovy folks volunteer to proof read them?

To see them:

1. checkout branch ws_beta6

2. ./runserver.sh

3. point browser at http://localhost:8181

Subject to corrections after review, everything is done for the next beta6 release.

[Tim Fox]

I intend to release beta6 on Monday.

Any comments before then most appreciated!

[Peter Ledbrook]

>> To see them:
>>
>> 1. checkout branch ws_beta6

Is a ./gen_site.sh necessary at this point? BTW, the README still
talks about ./genmanual.sh

>> 2. ./runserver.sh

Probably worth pointing out that you need vert.x on the path!

>> 3. point browser at http://localhost:8181
>>
>> Subject to corrections after review, everything is done for the next beta6
>> release.

Planning to take a look this morning.

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

[Peter Ledbrook]

>>> 2. ./runserver.sh
>
> Probably worth pointing out that you need vert.x on the path!

And then I got this exception: http://pastebin.com/DcD1s7Rx

Any ideas?

[Tim Fox]

On 12/04/12 09:41, Peter Ledbrook wrote:
>>> To see them:
>>>
>>> 1. checkout branch ws_beta6
> Is a ./gen_site.sh necessary at this point? BTW, the README still
> talks about ./genmanual.sh

You won't need to rebuild it unless you edit something, since I've
already built and added the generated html to github too

If you do want to build it you'll need to install the dependencies:
python markdown, xsltproc

I'll fix the README error :)

>>> 2. ./runserver.sh
> Probably worth pointing out that you need vert.x on the path!

What? You mean don't have vert.x installed on all your machines yet? ;)

>>> 3. point browser at http://localhost:8181
>>>
>>> Subject to corrections after review, everything is done for the next beta6
>>> release.
> Planning to take a look this morning.

Great. Thx!
> Peter
>

--
Tim Fox

Vert.x - effortless polyglot asynchronous application development
http://vertx.io
twitter:@timfox

[Tim Fox]

On Thursday, April 12, 2012 9:44:46 AM UTC+1, Peter wrote:

>>> 2. ./runserver.sh
>
> Probably worth pointing out that you need vert.x on the path!

And then I got this exception: http://pastebin.com/DcD1s7Rx

Any ideas?

Ah sorry. The API has changed from beta5 and I guess you just installed vert.x from master. I have updated web_server.js so it works with master. Pls try again

[Peter Ledbrook]

> Ah sorry. The API has changed from beta5 and I guess you just installed
> vert.x from master. I have updated web_server.js so it works with master.
> Pls try again

No problem. I wrote a web_server.groovy instead and run that ;)

Peter

[Peter Ledbrook]

> I've completed the Groovy API docs and tutorial.
>
> Would any Groovy folks volunteer to proof read them?

Just a few comments (the core API doc is long!):

# In the example `def id = container.deployVerticle(main)`, it's
really not clear what 'main' is. A string? If so, why's it not in
quotes? Is it an injected variable?
# `container.getConfig()` and `container.getLogger()` would more
typically be `container.config`, `container.logger`
# It's unusual to use quotes for map keys. I recommend removing them.
# There are semi-colons dotted around the examples
# Typo for this line: sock.write("hello", "UTF-162); <-- missing quote
# This example should probably refer to a Groovy script: `vertx deploy
foo.MyServer -instances 20`

One thing that does strike me is how all deployment is via scripts.
But what if you want to deploy a larger application that you have
decomposed into multiple classes? How do you deploy such an
application? Is there a packaging format?

Cheers,

[Tim Fox]

Thanks Peter,

On Thursday, April 12, 2012 11:24:49 AM UTC+1, Peter wrote:

> I've completed the Groovy API docs and tutorial.
>
> Would any Groovy folks volunteer to proof read them?

Just a few comments (the core API doc is long!):

# In the example `def id = container.deployVerticle(main)`, it's
really not clear what 'main' is. A string? If so, why's it not in
quotes? Is it an injected variable?

The sentence straight after says "See the chapter on "running vert.x" in the main manual for a description of what a main is."

Which goes into detail on what a main is.

Any suggestions welcome on how I can make this clearer.

 

# `container.getConfig()` and `container.getLogger()` would more
typically be `container.config`, `container.logger`

I can't see that in the version I am looking at. Are you looking at an old one?

 

# It's unusual to use quotes for map keys. I recommend removing them.

Again, think this is already fixed. Can you point me at the line?

 

# There are semi-colons dotted around the examples

Can you point me at specific cases?

 

# Typo for this line: sock.write("hello", "UTF-162);  <-- missing quote

Can't find this

 

# This example should probably refer to a Groovy script: `vertx deploy
foo.MyServer -instances 20`

Can't find this either!

 

One thing that does strike me is how all deployment is via scripts.

By scripts do you mean command line?

Yes, all deployment is via command line operations, as opposed to "dropping a war in a directory" like you do with many app servers.

This is more similar to node.js style.

 

But what if you want to deploy a larger application that you have
decomposed into multiple classes?

Classes can live in a hierarchy of class files in a directory or you can jar them up into a jar. It's up to you. Just makes sure the classpath you specify when deploying points at them.

If you mean multiple *verticles* rather than classes, then the normal way to do co-ordinate the starting is to write a simple script which starts them up in whatever order you require. You can also put your config in that script. (Code is config!)

Example of this here: http://vertx.io/wsver-0002/core_manual_js.html#using-a-verticle-to-co-ordinate-loading-of-an-application

 

How do you deploy such an
application?

The web app tutorial gives a good example of this.

 

Is there a packaging format?

No, you just specify the classpath when starting the verticle.

However we're also discussing (on the other thread today) about installing mods into a specific directory so they can be started by name, not by classpath.

[Peter Ledbrook]

> The sentence straight after says "See the chapter on "running vert.x" in the
> main manual for a description of what a main is."
>
> Which goes into detail on what a main is.
>
> Any suggestions welcome on how I can make this clearer.

Which just says it's a script name or a class. But is the argument a
string? A class literal? A file path to a script? Does it include the
file extension? At the moment, 'main' is simply a variable reference
but we don't know what that variable is.

>> # `container.getConfig()` and `container.getLogger()` would more
>> typically be `container.config`, `container.logger`
>
> I can't see that in the version I am looking at. Are you looking at an old
> one?

/core_manual_groovy.html#getting-configuration-in-a-verticle

I pulled the ws_beta6 branch this morning. However, just done another
pull and these have indeed been fixed.

>> # It's unusual to use quotes for map keys. I recommend removing them.
>
> Again, think this is already fixed. Can you point me at the line?

https://github.com/purplefox/vert.x/blob/ws_beta6/core_manual_groovy.md

Search for the line: def config = [ "foo": "wibble", "bar": false]

>> # There are semi-colons dotted around the examples
>
>
> Can you point me at specific cases?

container.deployVerticle("foo.ChildVerticle", config);
container.deployVerticle("verticle1.js", appConfig["verticle1Config"]);
...

Seriously, it would be easier if you grepped the source for semi-colons :)

>>
>> # Typo for this line: sock.write("hello", "UTF-162);  <-- missing quote
>
>
> Can't find this

I can only think we're looking at different files. If I search for
that string at the above GitHub URL, it's found.

>>
>> # This example should probably refer to a Groovy script: `vertx deploy
>> foo.MyServer -instances 20`
>
> Can't find this either!

See above :) Have you forgotten to push? Committed to a different branch?

>> One thing that does strike me is how all deployment is via scripts.
>
> By scripts do you mean command line?

No, as in MyApp.groovy - a single file that's a script.

> Yes, all deployment is via command line operations, as opposed to "dropping
> a war in a directory" like you do with many app servers.
>
> This is more similar to node.js style.
>
>>
>> But what if you want to deploy a larger application that you have
>> decomposed into multiple classes?
>
> Classes can live in a hierarchy of class files in a directory or you can jar
> them up into a jar. It's up to you. Just makes sure the classpath you
> specify when deploying points at them.

So, roll it yourself :) I think this comes back to how you make sure
stuff appear on the classpath, which as I understand it means running
vert.x as a server with everything necessary already on the classpath.
Then you can deploy your apps. Not sure I buy into this model, but
that's a separate discussion/argument.

Or have I got that wrong? Anyway, let's sort out the docs first.

[Tim Fox]

On Thursday, April 12, 2012 12:20:03 PM UTC+1, Peter wrote:

> The sentence straight after says "See the chapter on "running vert.x" in the
> main manual for a description of what a main is."
>
> Which goes into detail on what a main is.
>
> Any suggestions welcome on how I can make this clearer.

Which just says it's a script name or a class. But is the argument a
string? A class literal? A file path to a script? Does it include the
file extension? At the moment, 'main' is simply a variable reference
but we don't know what that variable is.

It's the script name. I.e. foo.groovy

I will make it absolutely explicit since it seems "script name" is ambiguous (?)

 

>> # `container.getConfig()` and `container.getLogger()` would more
>> typically be `container.config`, `container.logger`
>
> I can't see that in the version I am looking at. Are you looking at an old
> one?

/core_manual_groovy.html#getting-configuration-in-a-verticle

I pulled the ws_beta6 branch this morning. However, just done another
pull and these have indeed been fixed.

I fixed them yesterday actually ;)

 

>> # It's unusual to use quotes for map keys. I recommend removing them.
>
> Again, think this is already fixed. Can you point me at the line?

https://github.com/purplefox/vert.x/blob/ws_beta6/core_manual_groovy.md

Search for the line: def config = [ "foo": "wibble", "bar": false]

Thanks. Fixed.

 

>> # There are semi-colons dotted around the examples
>
>
> Can you point me at specific cases?

    container.deployVerticle("foo.ChildVerticle", config);
    container.deployVerticle("verticle1.js", appConfig["verticle1Config"]);
   ...

Seriously, it would be easier if you grepped the source for semi-colons :)

Yes, sorry for the laziness. Fixed.

 

>>
>> # Typo for this line: sock.write("hello", "UTF-162);  <-- missing quote
>
>
> Can't find this

I can only think we're looking at different files. If I search for
that string at the above GitHub URL, it's found.

I still can't find it (maybe I fixed it already and forgot), and I've done a recursive grep thru the whole source.

 

>>
>> # This example should probably refer to a Groovy script: `vertx deploy
>> foo.MyServer -instances 20`
>
> Can't find this either!

See above :) Have you forgotten to push? Committed to a different branch?

Ah, I found it!

 

>> One thing that does strike me is how all deployment is via scripts.
>
> By scripts do you mean command line?

No, as in MyApp.groovy - a single file that's a script.

> Yes, all deployment is via command line operations, as opposed to "dropping
> a war in a directory" like you do with many app servers.
>
> This is more similar to node.js style.
>
>>
>> But what if you want to deploy a larger application that you have
>> decomposed into multiple classes?
>
> Classes can live in a hierarchy of class files in a directory or you can jar
> them up into a jar. It's up to you. Just makes sure the classpath you
> specify when deploying points at them.

So, roll it yourself :) I think this comes back to how you make sure
stuff appear on the classpath, which as I understand it means running
vert.x as a server with everything necessary already on the classpath.
Then you can deploy your apps. Not sure I buy into this model, but
that's a separate discussion/argument.

Or have I got that wrong?

In a "traditional" Java-style app server deployment you would probably have some kind of xml descriptor describing what components to start, then you'd have the components themselves, and any dependencies (e.g. other jars), then you'd probably have another xml with your config. You'd then wrap all of that up in a jar or zip and deploy it.

With vert.x as it currently is, you'd most likely create a directory, put all your classes and zips in it, and create a main script that says what components to load. The main script *kind of* takes the place of the xml descriptor (code is config), except it's more expressive (e.g. you can load things in whatever order you want), and it can also contain your config (e.g. as JSON literals). Alternatively you can supply your config as a separate JSON file, it's up to you.

So it's not a whole lot different to the trad deployment, except it's more concise and expressive, and no xml (yippe). I guess you could think of the directory you put your app in as the exploded "war/ear/whatever".

Now, going further, what I suggested about modules would allow all your app dirs (exploded archives) to live in some well defined place, so you could reference or start them with just vertx run <mod_name> without having to specify any classpath.

Feel free to start another thread (or use the mods thread) to discuss this more :)

[Tim Fox]

On Thursday, April 12, 2012 12:20:03 PM UTC+1, Peter wrote:

>> One thing that does strike me is how all deployment is via scripts.
>
> By scripts do you mean command line?

No, as in MyApp.groovy - a single file that's a script.

So.. not all deployment is via script, i.e. you can run verticle directly without a co-ordinating script:

vertx run server.js

vertx run org.foo.MyServer

That's common when your "application" is small or you want to start and stop things independently from the command line.

For larger deployments it's likely you'd you use a script (another verticle) as a co-ordinator

 

[Peter Ledbrook]

> It's the script name. I.e. foo.groovy
>
> I will make it absolutely explicit since it seems "script name" is ambiguous
> (?)

Replacing 'main' with the string-literal "foo.groovy" would certainly
help I think. The main manual should probably include some more
examples too, highlighting that:

# 'main' is a string
# it's a script name *with* extension or a fully-qualified class name
# it does not include a path to the script.

>> /core_manual_groovy.html#getting-configuration-in-a-verticle
>>
>> I pulled the ws_beta6 branch this morning. However, just done another
>> pull and these have indeed been fixed.
>
>
> I fixed them yesterday actually ;)

Yeah, I don't know why the `git fetch` and `git co -b ...
upstream/ws_beta6` didn't seem to get the latest. Nevermind, sorted
now.

> I still can't find it (maybe I fixed it already and forgot), and I've done a
> recursive grep thru the whole source.

I've caved and sent a pull request :)

[Peter Ledbrook]

> For larger deployments it's likely you'd you use a script (another verticle)
> as a co-ordinator

It's not clear how a coordinator script should work. For example,
let's say I run `vertx start` in some arbitrary location (not in a
vert.x application directory). I can then do a separate `vertx deploy
foo.groovy` as long as the script is standalone, i.e. doesn't require
any other JARs etc it can't resolve itself. Is that correct?

What I wouldn't be able to do is run `vertx deploy foo.groovy` from a
Vert.x app directory and expect the whole directory to be deployed to
wherever `vertx start` is running, right?

I guess what I'm really getting at is how `vertx start` works. My
current understanding is that I can launch that command in an
application directory and then deploy a script from elsewhere, but I'm
struggling to understand the value of this approach.

Anyway, I'll read the busmods thread more fully and get back to you.

[Tim Fox]

On 12/04/12 14:10, Peter Ledbrook wrote:
>> For larger deployments it's likely you'd you use a script (another verticle)
>> as a co-ordinator

I don't think most people will use vertx start / vertx deploy. For
deploying apps it is easier to just use vertx run.

You then just cd to wherever your app is and execute vertx run. This is
the same model node.js employs.

(This is 99% likely what we'd have to do on a cloud deployment like
cloudfoundry )

About vertx start / deploy:

> It's not clear how a coordinator script should work. For example,
> let's say I run `vertx start` in some arbitrary location (not in a
> vert.x application directory). I can then do a separate `vertx deploy
> foo.groovy` as long as the script is standalone, i.e. doesn't require
> any other JARs etc it can't resolve itself. Is that correct?

The script doesn't need to be standalone - it can reference as many
other scripts and jars as it likes on the classpath.

> What I wouldn't be able to do is run `vertx deploy foo.groovy` from a
> Vert.x app directory and expect the whole directory to be deployed to
> wherever `vertx start` is running, right?

When you execute vertx deploy (or vertx run for that matter), nothing
gets moved or copied to another place. It's not like the CF command line
tool (vmc) which physically copies stuff to the server.

All that happens is it tells the server to open the main script that you
specified with the classpath that you specified and run it.

So the working directory of the verticle is wherever you ran vertx start
from. This differs from vertx run where the working directory is
wherever you ran vertx run from.

> I guess what I'm really getting at is how `vertx start` works. My
> current understanding is that I can launch that command in an
> application directory and then deploy a script from elsewhere, but I'm
> struggling to understand the value of this approach.

The value with vertx start as opposed to vertx run is you can have a
single JVM instance hosting many apps, so there's less overhead from the
JVM.

> Anyway, I'll read the busmods thread more fully and get back to you.
>
> Peter
>

--

[Peter Ledbrook]

> The value with vertx start as opposed to vertx run is you can have a single
> JVM instance hosting many apps, so there's less overhead from the JVM.

OK, thanks. That's cleared things up in my head now. Still, if you do
`vertx deploy foo.groovy`, doesn't that serialise the script to the
'server'? In other words, foo.groovy doesn't have to be in the
directory where `vertx start` was executed from. Or am I wrong on that
as well?

[Tim Fox]

On Thursday, April 12, 2012 3:06:45 PM UTC+1, Peter wrote:

> The value with vertx start as opposed to vertx run is you can have a single
> JVM instance hosting many apps, so there's less overhead from the JVM.

OK, thanks. That's cleared things up in my head now. Still, if you do
`vertx deploy foo.groovy`, doesn't that serialise the script to the
'server'?

The server (where you called vertx start) and the place where you're calling vertx deploy have to have access to the same filesystem.

Then all that happens is the server gets sent the classpath where all the paths have been made absolute. The server can use that same path (since it's absolute) to create a URLClassloader which uses the path (file url) to load the scripts.

[Tim Fox]

So from the point of view of the verticle the only difference is where the working directory is.

For deploying, wd = where vertx start was called

For running wd = where vertx run was called

The wd issue is tricky - it's not possible in Java to set the wd

[Tim Fox]

Just had a thought - might be able to solve this by vert.x automatically adjusting any paths used in calls to the vert.x file system API such that the verticle "thinks" it's running in the place from where vertx deploy was called (or where the mod is installed).

This means semantics of vertx deploy and vertx run would be identical from the verticle's POV

It also means you would be able to package up entire apps into mods along with static files (e.g. a web app with static files) and deploy it as a mod and when it runs it would think "." is the mod dir :)

[Antoine Roux]

Hello,
I am reading the tutorial. I have just a few remarks:

• In several places, you reference the Mongo persistor with the ruby or the Javascript wrapper. Maybe, from a Groovy perspective, it is better to user the plain Java persistor?
• The same goes for the auth manager. You use auth_mgr.js but from Groovy I guess we would rather use the Java busmod
  
• Save the edited app.rb and restart it => Save the edited App.groovy and restart it.

I can group those comments in a pull request, if you agree with the first two.

Antoine

[Tim Fox]

Antoine,

Thanks. Yes I agree :)

Please feel free to send a pull request