|
Replies:
7
-
Last Post:
Apr 21, 2008 10:43 AM
by: deronj
|
|
|
|
|
|
|
Wonderland 0.5 Cell and Communication API's
Posted:
Apr 11, 2008 5:05 PM
|
|
|
The initial draft of the 0.5 Cell and Communication API's are ready for review. The API javadoc can be found here http://download.java.net/lg3d/wonderland/api-update/api/index.html
If you are creating Cells (or plan to) please take some time to review the API's and ensure they meet your needs.
These API's form the lowest level of the Wonderland API hierarchy, there will be further abstractions and utility code built on top of them so bare that in mind if you don't find your favourite feature 
|
|
|
|
|
|
|
Re: Wonderland 0.5 Cell and Communication API's
Posted:
Apr 13, 2008 9:22 AM
in response to: paulby
|
|
|
This is very good for a first draft, and already contains many of the "atomic" needs for cells and comms.
What is not easy for us to see (yet) is the "generic" high level functionality that will be available, ie what most developers and advanced users of Wonderland will all usually need, and as a consequence would be nice to get in 0.5
For instance:
* a configurable Client GUI or alternatively a rich API together with enough examples (Java clients and at least one Applet client)
* a "manager-level" client (GUI or CLI or param file) which unlike normal clients can:
- start/shutdown WL servers
- shoot down a User or kill a Session
- log in to world even if max # of users has been reached
- broadcast a message to all Users
- set depth/distance of rendering (ie configure CellCache)
* easily configure audio sources as objects with attached sound files
* move an object, and the various scripting capability that I entered in a previous post
michel
|
|
|
|
|
|
|
|
|
Re: Wonderland 0.5 Cell and Communication API's
Posted:
Apr 15, 2008 9:27 PM
in response to: micheldenis
|
|
|
Hi Michel,
All the areas you mention are obviously very important, they will be addressed at various stages of the API design. The main goal of carefully laying out the key api's at this stage is that once those API's are labeled as StableAPI we will not make any backward incompatible changes (all the API's currently labeled as ExperimentalAPI are destined to become StableAPI).
From the points you raise there are a couple which touch on the cell and network api. The server management system will be implemented as a dedicated Connection type. The goal behind the Connection mechanism is to allow us the break the various clients into reusable components that can be mixed and matched depending on requirements and client capabilities. Also the ClientCapabiities allow us tune how we service a particular client (eg lower network bandwidth), The MovableCell provides the ability for user level movement (of the cell), adding a script interface to this is probably the next thing I'll experiment with. For Cells that want to do synchronized movement/animation of their content, they will implement the ChannelCell interface (or subclass a Cell that already implements it) to gain a cell specific channel.
Rgds
Paul
|
|
|
|
|
|
|
|
|
Re: Wonderland 0.5 Cell and Communication API's
Posted:
Apr 18, 2008 6:24 AM
in response to: paulby
|
|
|
Paul,
Thanks for posting the API docs. My comments focus on the cell related classes and APIs, rather than the communication and user parts of the API. I only have really very minor (borderline anal) comments included below. Almost all are suggestions to improve the documentation, but again, very minor. Hope this helps!
Comments about the Overview at:
http://download.java.net/lg3d/wonderland/api-update/api/index.html
In general, this Overview can be potentially huge -- it does a good job of describing the architecture, but architectural block diagrams may be necessary either here or in a separate architecture document.
Cell subsection
1. Is there a class associated with static cells to complement Movable cells? That is, if I write a new static cell, what do I subclass? Cell?
2. It is unclear what is meant by "dynamic content" when describing movable cells. Does it mean strictly a cell that can move? Or a cell whose visual appearance can change?
3. Can only movable cells have a ChannelCell? I can imagine cells that do not move may also want to communicate with the server-side cell class.
Package org.jdesktop.wonderland.server.cell
1. It is unclear to which class references to getComputedWorldBounds and getCacheVWBounds apply. The discussion of local vs. world coordinates is good (and necessary here).
2. It may be a good idea to define what is meant by a 'live' cell here.
Interface CellDescription
1. Particularly so since Wonderland is a visual environment, the use of the term 'mirror' to describe this interface is a bit confusing. How about something like: "CellDescription is a light-weight interface that returns the pertitent information about a cell." (The term 'mirror' implies some form of visual reflection).
2. For getContentsVersion(), getTransformVersion(), getPriority() is there some defined valid range for the return values?
3. What is contents version? transform version?
4. Are there any circumstances that getLocalBounds(), getTransform() can return null?
5. I don't see where this interface is used in other classes?
CellMO class
1. In CellMO(BoundingVolume, CellTransform), must CellTransform also not be null?
2. In getComputedWorldBounds() for a non-live cell, what does this method return? null?
3. In addChild(), are you permitted to add the same cell object twice to a hierarchy? (I'm guessing not).
4. In setPriority(), what happens if a negative priority is given?
5. Can setupCell(), reconfigureCell() ever fail? (e.g. invalid or null setup class).
6. In getAllChildrenRefs(), what exactly is a reference for a child? Is it the Darkstar ManagedReference?
7. In detach(), should specify that multiple invocations has no side effects.
CellManagerMO class
1. Why is getCell() static?
2. Is there just one root cell? multiple? (seems so from getRootCells() method)
3. (Can initialize() be folded into the first call of getCellManager()?)
Cell class
1. So that it may be subclassed outside of the package, this class needs either a public or protected constructor.
2. What's the relationship between live/unlive states of cells on the server and cells contained within the client cache? Do unlive cells get removed from the client-side cache? When the server moves a cell into the 'unlive' state, how does its state transition as returned by getStatus()?
3. It would be good to define the valid state transitions for cell states returned by getStatus() and setStatus().
4. It's unclear what 'cached' bounds means.
5. If a new cell type wants to take action upon a change in the cell's state, does it subclass setStatus()? Or does adding a listener to this class for state changes make sense?
CellManager class
1. What does 'currently loaded Cells' mean? Loaded on the server? Live cells?
2. In add/removeCellMoveListener(), remove references to 'entity' cells. I believe that is old terminology.
|
|
|
|
|
|
|
|
|
Re: Wonderland 0.5 Cell and Communication API's
Posted:
Apr 18, 2008 1:45 PM
in response to: paulby
|
|
|
Here are my questions and comments:
Overview
--------
Avatars and Cameras are examples of a view.
-->
Is Camera a Wonderland class? It is confusing to see a capitalized noun. The first impression
of such a noun is that it is a Wonderland class. Also, What is the relationship between an avatar and a camera?
The View interface speaks of a Camera being an attribute of a View. The same ambiguity exists in the class
description of View.
Small device: No avatar, View controlled by View Handler.
-->
Where is View Handler documented?
specific Connetion is a singleton and they must be correctly
-->
Connection is misspelled
Depending on the ... client capabilities ... the same mechanism also
provides for multiple communication channels allowing, for example,
support for clients with varying network bandwidth capabilities.
-->
I didn't understand this. I didn't see anything about communication channels
in the ClientCapabilities.
MovableCell which contain dynamic content
-->
I thought that the only difference between a static and movable cell is that
the movable cell can change its transform relative to its parent. This sentence
seems to define a constraint on the cell content itself. Does this mean that you
can't have a sub scene graph in a static cell which changes over time? Maybe we
we should define four types: Stationary Static, Stationary Dynamic, Movable Static,
and Movable Dynamic?
the static cells can be updated but this is a heavyweight operation
and may briefly cause a pause in client rendering).
-->
Just out of curiosity, why?
MovableCell implements ChannelCell thus providing a communication
Channel over which messages are sent/received to keep the cell state
(loosely) synchronized.
-->
Delete the "(loosely)" and explain in a subsequent parenthetical sentence
that the synchronization is allowed to be loose and exactly what you mean by
loose.
What happens if a Movable cell needs to move between two parents? This case isn't
mentioned. Does it break the rule "parent bounds must enclose child bounds?"
The server Cell Cache (org.jdesktop.wonderland.server.cell.CellCacheMO ) is responsible for
determining which cells are potentially visible to a client use
-->
Should be "uses."
Each client application connected to the wonderland server is
represented by a Session on both the client and the server.
-->
Capitalizing Session implies that it is a Wonderland class, but there is no
such class. Did you mean to say "Darkstar session?"
There is no class
A single user can have multiple concurrent sessions.
-->
Does that mean that a user can be logged in twice? Or did you mean that
a Wonderland client program can have multiple concurrent sessions.
This information is used by the Cell system to determine the content
that is delivered to a client and the cell channel to which a client
is attached.
-->
What are the different cell channels which different bandwidth clients can be attached.
Is the ClientCapabilities class the place I should provide access to the Shared App
"ExecutionCapabilities," that is, the types of programs a client can execute?
org.jdesktop.wonderland.client
------------------------------
ClientContext and ClientContext3D need more documentation. Some sort of overview
doc would help.
org.jdesktop.wonderland.client.comms
------------------------------------
General comment on package:
This documentation is too sparse and disjoint. There is nothing which indicates how all of these
classes are used together to create a connection. An example in the package overview
is necessary.
WonderlandServerInfo
All data to uniquely identify a servre
-->
Server is misspelled.
WonderlandSession
ClientConnection getConnection(ConnectionType type)
Get the attched ClientConnection for the given ConnectionType.
ClientConnection getConnection(ConnectionType type, java.lang.Class clazz)
Get the attched ClientConnection for the given ConnectionType.
-->
The documentation for these two methods is identical.
org.jdesktop.wonderland.server.comms
------------------------------------
General comment on package:
This documentation is too sparse and disjoint. There is nothing which indicates how all of these
classes are used together to create a connection. An example in the package overview
is necessary.
org.jdesktop.wonderland.common.messages
---------------------------------------
OKMessage
Create a new OK message in response to the a request message with the given id.
^ the a ?
Who sends this message and when?
org.jdesktop.wonderland.server.cell
-----------------------------------
CellDescription
Who creates this? How is it related to CellMO? I didn't see any reference to it in the CellMO doc.
What is the purpose of this class?
CellMO
Return the priorty of the cell. A cells priority dictates the order in which it is loaded by a client. Priortity 0 cells are loaded first, followed by subsequent priority levels. Priority is only a hint to the client, it has no effect on the server The default priority is 5
->
Priority is misspelled twice: priorty and priortity.
Is the priority the priority of the cell download or the cell contents download?
public void setupCell(BasicCellMOSetup setup)
public void reconfigureCell(BasicCellMOSetup setup)
-->
BasicCellMOSetup was not found in the docs.
addSession: Add a client session with the specified capabilities to this cell. Called by the ViewCellCacheMO as part of makeing a cell active
-->
Making is mispelled.
changeSession: Called to notify the cell that some aspect of the client sessions capabilities have changed. This call is made from the ViewCellCacheOperations exectue method returned by addSession.
-->
Execute is misspelled.
setupCell(BasicCellMOSetup setup)
-->
I found the use of the term setup in this class confusing in Rel 0.3 and I was hoping it would go away.
It's too easy to confuse this with SetupData. These two are entirely different things so don't use the
same name.
getViewCellCacheRevalidationListener
-->
What is the purpose of this listener? Who creates it?
And, under what circumstances would this method return null?
isLive: Get the live state of this cell. live cells are connected to the world root, inlive cells are not
-->
I guess you mean "unlive?"
And, what is the difference between live and "active?" Active is a term used elsewhere in this doc.
contentChanged
-->
What exactly does this mean? Each time any client or the server changes the cell contents this must
be called? If so, is the use of this interface required? Why have a cell general mechanism for this?
I can forsee that cell-specific mechanisms might want to be used.
And, how is this method invocation perceived on the client side? I didn't see any corresponding method
in the client.cell.Cell API which would be invoked in the client when contentChanged is invoked on the server.
CellSessionProperties
public CellSessionProperties(ViewCellCacheRevalidationListener viewCacheOperation,
java.lang.String clientCellClassName,
CellSetup clientCellSetup)
CellManagerMO
java.util.Collection getCells(com.jme.bounding.BoundingVolume b, java.lang.Class[] cellClasses)
Traverse all trees and return the CellDescription for the cells which are within the specified bounds and are of the given Class
-->
Shouldn't the return type be Collection<CellDescription>? And you need to say that it returns a COLLECTION of CellDescription objects for the cells ...
Ditto for getRootCells.
getRootCells()
Return the collection of descriptors of the root cells for the world.
-->
addCell seems to imply that there is a single root cell ("Add the cell to the rootCell").
But the documentation for getRootCells seems to imply that there are multiple root cells.
Which is it?
SimpleTerrainCellMO
-->
There isn't enough doc for this. For example, what is the purpose of the constructor arguments?
MovableCellMO
-->
There is no documentation for this. So it is hard to review the AvatarMO class which extends this.
org.jdesktop.wonderland.client.cell
-----------------------------------
CellStatus
-->
Trying to follow a link for this gives Not Found error.
CellCacheConnection.CellCacheMessageListener
-->
loadCell needs doc for params.
CellCacheConnection(ClientView clientView)
-->
Trying to follow the ClientView link gives Not Found error.
ChannelCellAdapter
-->
I don't understand the purpose of this class.
|
|
|
|
|
|
|
|
|
Re: Wonderland 0.5 Cell and Communication API's
Posted:
Apr 18, 2008 3:10 PM
in response to: paulby
|
|
|
On the server-side, CellMO are managed objects -- that is, their state is persisted by Darkstar. That means any call that modifies the cell tree (e.g. addChild(), detach()) or updates a cell's state (e.g. setLive()), needs to happen within a Darkstar transaction. This should probably be specified.
|
|
|
|
|
|
|
|
|
Re: Wonderland 0.5 Cell and Communication API's
Posted:
Apr 21, 2008 5:07 AM
in response to: paulby
|
|
|
Paul
this looks like a huge amount of work you guys have done here; great stuff.
I took a look at the overview to try to get my head around the overall architecture provided by the API and I'm really struggling to see how all this fits together. Unfortunately, until I can get that kind of perspective, I can't really make any headway into the details of the API.
I think the overview needs to provide some kind of real architectural perspective of how all the pieces fit, even just the ones in this API. One way of doing that would be to clearly outline the roles and responsibilities of each class (rather than the detail of the API) and also to provide some diagrams that provide a view of the relationships between the objects modelled by the classes. This could be a class diagram and an interaction diagram, say.
So, I'll delay commenting further till I can find my way through the trees.
cheers
Bernard
|
|
|
|
|
|
|
|
|
Re: Wonderland 0.5 Cell and Communication API's
Posted:
Apr 21, 2008 10:43 AM
in response to: bernard_horan
|
|
|
I agree with Bernard. Lots of good stuff but it's hard to know how to use it. One thing I would like to see is a tutorial on how to build a new cell type.
|
|
|
|
|
java.net RSS
