Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 349690

Summary:	Document use of Virgo Snaps
Product:	[RT] Virgo	Reporter:	Chris Frost <eclipse>
Component:	documentation	Assignee:	Chris Frost <eclipse>
Status:	CLOSED FIXED	QA Contact:
Severity:	enhancement
Priority:	P3	CC:	dmitry
Version:	3.0.0.M05
Target Milestone:	3.0.0.RC1
Hardware:	PC
OS:	Mac OS X - Carbon (unsup.)
Whiteboard:
Bug Depends on:	350865
Bug Blocks:

Description Chris Frost

2011-06-17 09:50:34 EDT

Snaps requires it's own documentation that should be packaged and distributed with Snaps.

I propose the following table of contents.

1. Requirements (What version of Virgo will Snaps work with, (3+ and not Jetty)
2. Snaps concepts (Explain the theory of how it works,
3. Installing (Put bundles and plan in repo and add plan to initial artifact)
4. At a medium level show them how to develop a Snaps application. Referencing the menu bar sample.
5. Talk about the Snaps API and referencing the parent Servlet Context etc...
6. Conclusions (here are some other sample apps and some other things you can do e.g. styling bundles)

I think this covers everything and gives a ruff idea about what should be going in. Some areas will need some good exploration, especially 5. Some features are not covered by samples apps either, may want to consider that.

Comment 1 Chris Frost

2011-06-17 12:39:01 EDT

Dmitry, could you look over this ruff table of contents and see if there is anything you think I missed.

Comment 2 Dmitry Sklyut

2011-06-26 17:40:56 EDT

I think documentation should go into some detail on how request is routed by the SnapFilter.  Mention that only single level urls are supported currently.  That is /foo/bar is not supported for the snap context prefix.

Should also caution against tunneling into host servlet context, request attributes, session attributes as it might cause CCE or other worrisome issues with class-space consistency and versioning (host imports v=1.0.0 and snap 1.1.0 of some support package - and that class sits in the some sort of scope).

In my mind snap should be as independent from host as possible and any communication between two (if required) should go through service registry.

Host is mostly just an invisible pane around the snap vs. a root_web_app context (in spring terms).

Comment 3 Chris Frost

2011-06-30 13:05:38 EDT

Docbook project added in the snaps repo and integrated to the build.

Comment 4 Chris Frost

2011-07-14 12:13:13 EDT

Done and pushed to master