[wsrp-interfaces] Draft spec v0.4, feedback

[Alejandro Abdelnur <alejandro.abdelnur@sun.com>]

It looks like things are shapping, great job.

Following some feedback after a first pass.

Regards.

Alejadnro

01-------------------------------------------------------------------
Section 3.7 page 21 lines 32-34

The first part of the sentence refers to a two phase protocol 
interaction between a Consumer and a Producer but it does not mention 
that this interaction is with a specific entity, the second part of the 
sentence talks about the effect of the interactions on other entities. 
This is confusing, the first part should also refer to entities.

02-------------------------------------------------------------------
Section 3.7 page 21 line 37

The use of the two phase capability is optional en dependent on the 
"entity" not on the consumer.

03-------------------------------------------------------------------
Section 3.7 page 21 line 43

Why a consumer would interact with the 'published state of an entity'?
I thought we decided that the consumer would not store properties.

04-------------------------------------------------------------------
Section 3.7 page 22 lines 2-4

It is not clear that the side effects to other entities happen in the 
performAction.

05-------------------------------------------------------------------
Section 3.10.2 page 23 line 25

Why would 'setProperties' require the context of a session?

06-------------------------------------------------------------------
Section 4 page 24 lines 23-33

consumerHandle and consumerState.

One is an opaque handle and the other is a placeholder for producer 
data. Both have are obtained by at registration, both have to be stored 
by the consumer.

Wouldn't be enough having just a consumerHandle and it's up the to 
producer to use an opaque handle or to store state in it?

07-------------------------------------------------------------------
Section 4 page 24 lines 35-36

Why are we overloading the getDescriptor to return different 
'descriptions' types base on the 'handle' type?

Wouldn't be cleaner to have a getProducerDescriptor and a 
getEntityDescriptor?

08-------------------------------------------------------------------
Section 5.2 page 27 line 37

A consumer has to keep the entityContext for the life duration of
an entity? Wouldn't a handle be enough? And during the context is
kept only during the life duration of a session ?

09-------------------------------------------------------------------
Section 5.4 page 28 line 35

Again, why are we overloading methods for different handles?
I would prefer a releaseProducerHandle and a releaseEntityHandle.

10-------------------------------------------------------------------
Section 6.1 page 30 line 4

Isn't previousWindowState missing ?

What is the use case of having the consumer storing the previous 
PortletMode (and WindowState)?

11-------------------------------------------------------------------
Section 6.1 page 29-30

The markupContext should have a isRefresh element to indicate if the 
getMarkup is being called in a request that has been targeted to it or 
to another entity.

This will help entities that do not do actions to deal with the reply 
problem. In particular, in the Java world, when a portlet is delegating 
to servlets and JSPs.

12-------------------------------------------------------------------
Section  6.1 page 31 line 11

the getMarkup should also receive the clientParameters if any.

This will also help entities that do not do actions to deal with the 
reply problem. In particular, in the Java world, when a portlet is 
delegating to servlets and JSPs.

13-------------------------------------------------------------------
Section 6.2.2 page 32 line 8-15

This paragraph is not necessary true.

A consumer could use a javascript artifact to have the navigationalState 
store somewhere within the document.

Restricting the getMarkup not to return navigational state is too 
implementation specific.

14-------------------------------------------------------------------
Section 10 page 45

homeInfo is twice, I believe one should be homeInfo and the other workInfo.

15-------------------------------------------------------------------
Section 11.4 page 48

Why consumerContext has the userID? This will require consumers to clone 
or create a consumerContext for each call for a different userID. userID 
should be a separate parameter so a consumer can reuse the same 
consumerContext for all its iteractions with a producer.

16-------------------------------------------------------------------
Section 11.4 page 49

sendPublishedState, same as comment 03

But if we have this functionality. Would this be at producer level or at 
entity level?

17-------------------------------------------------------------------
Section 11.6 page 50 line 41

Should an entity be able to set its own title?. If so, title information 
is missing from the markupResponse

18-------------------------------------------------------------------
Section 11.11 page 55

We never came out with clear definitions for any predefined roles.
I've thought that we agreed on having a clear definition before adding 
them to the spec.

19-------------------------------------------------------------------
Section 11.12 page 55

Why the constants are of type int instead of type string ?

Detach is not defined byt a constant is.

---------------------------------------------------------------------