RE: [wsia] [wsrp-interfaces] Draft spec v0.5

[Sasha Aickin <AlexanderA@plumtree.com>]

The spec is sure shaping up.  I have some random questions & comments about the interfaces.  Most of them are from reading the last version, though, and I apologize in advance if I don't correctly pick up on changes between 0.4 and 0.5.  

Also, I decided not to embed my comments in the document since others seem to have problems with that.

(1)  I'm interested in Alejandro's question about why consumerContext on getDescription has both a consumerHandle and a consumerState.  As I read the spec currently, the consumerHandle and consumerState are both opaque strings sent from the Producer to the Consumer that MUST be sent back by the Consumer.  Rich responds in the document that Producers can't modify the consumerHandle in modifyRegistration, but I don't understand why this needs to be true.

(2)  Count my vote for making getDescription into at least two methods.  Right now it has disjunct return arguments depending on whether the handle is for an entity or a consumer; that seems like me to be a red flag denoting the need to decompose.

(3)  In the description for userContext in getDescription, we say:

"Since this operation does not receive any reference to a possible session, the userContext MUST be passed on each invocation."

This sentence implies to me that the other arguments to getDescription are all optional (since they don't say that they MUST be passed), but I had sort of assumed that an argument was required unless specifically noted.  Which is correct?

(4)  In section 5, we say: 

"The Consumer MAY end the relationship via an explicit call to releaseHandles() method, whereas the Producer MAY end the registration by invalidating the registration identifier."

I think we mean that the Consumer MUST end the relationship via an explicit call to releaseHandles, right?  If the Consumer MAY end the relationship with releaseHandles, then presumably a lot of Consumer would never call the method.

(5)  For registrationData, section 11 says that consumerName should be globally unique.  How do we want to suggest assigning a name in a globally unique way?

(6) For registrationData, section 11 says that characterSetConversion indicates if the Consumer intends to convert character sets.  Why is this surfaced in the spec?

(7) consumerContext's member sendPublishedState seems useful on some calls (like cloneEntity) but not on others (like registerConsumer).  Further, the effects of the sendPublishedState flag are only explicitly described in the spec for cloneEntity and setProperties.  I think we should describe what sendPublishedState does for each call, and we should probably take it out of the signatures of several of the methods.

(8) In section 5.1, we say:

"The Consumer SHOULD persistently store the consumerContext. If the Consumer cannot persist the context, it must attempt to release the consumerHandle using the releaseHandles() method when exiting the current conversation."

I think it makes more sense not to try to commit to a notion of persistence on the Consumer but instead to say: "The Consumer MUST use releaseHandles() on every consumerContext that is returned as a result of registerConsumer()."  This is the only requirement that the spec cares about; from the spec's perspective it doesn't matter how the consumer handle is stored.  Along the same lines, I think that the following text in the description of cloneEntity:

"The handle of the new ConsumerConfiguredEntity must be persisted by the Consumer and released when it is no longer needed. If the Consumer is unable to persist the entity it must release it before the conversation ends."

should be changed to:

"The handle of the new ConsumerConfiguredEntity MUST be released when it is no longer needed."

(9)  In section 5.1 in the description of modifyConsumer, we say:

"A consumerContext is returned since the Producer MAY store state for this registration in this structure for the Consumer to supply on future invocations. The Producer MUST NOT modify the consumerHandle contained within this data structure."

If the Producer MUST NOT modify the consumerHandle, then why are we even letting the Producer return a handle at all?  If the only thing the Producer can change is the consumerState, I think that should be the only thing the operation returns.  As it is, the operation's signature is confusing; I could easily see a Producer implementation mistakenly returning a new consumerHandle or a Consumer implementation mistakenly accepting a returned consumerHandle.

(10)  Why does cloneEntity take in an array of properties both in the entityContext argument and in the entityProperties argument?  For that matter, why does cloneEntity allow the user to modify properties at all?  Wouldn't it be simpler in the spec to just call cloneEntity and modifyEntity to achieve the same goal?

(11)  In the description for entityState in cloneEntity we say:

"If a Producer sets this field, the Consumer MUST return the supplied value on future invocations."

I thought we were allowing timeouts for all kinds of state tokens passed back and forth, but this sentence refutes that.  How can entity state be retired?  Will releaseHandles do it?

(12) I totally agree with Alan's & Andre's comments about the releaseHandles method.

(13) I share Alejandro's question about the previousMode argument to getMarkup.  Also, what does previousMode mean exactly?  If for example the user last logged in a week ago, is the portal expected to remember the modes of every entity?  Is the mode tracking keyed on a portal/portlet/entity basis (and thus shared among many users), a portal/portlet/entity/user basis (and thus shared among one user's several sessions) or on a portal/portlet/entity/user/session basis?  In my mind, this argument seems like unnecessary complexity without a clear use case.

(14) Do we expect the markupType argument to getMarkup() to be a MIME type?  If so, we should explicitly state that.

(15) The argument secureClientCommunications to getMarkup() seems to me to demand more than a boolean.  It would be nice (with some sort of extensible string) to indicate what level of security is being used with the client, what kind of network is being used, etc.  If people would rather have it be just a boolean, then I think we should name it something like SSLTLSClientCommunications to be more explicit about what it denotes.

(16) The description for sessionID in MarkupResponse says:

"The Consumer MUST supply this ID on subsequent invocations [A205]."

Then the description for expires in MarkupResponse says:

"This is provided as a hint for when the Consumer MAY also cleanup resources related to this sessionID."

The uses of MAY and MUST here are contradictory, and for me they leave open the question about if a Consumer can discard a sessionID before the Producer indicated expires time.  I thought we had agreed that a Consumer could time out sessionIDs whenever it wanted to, but the MUST sentence here contradicts that.  What do folks think?

(17) The description of the transportHeaders argument to getMarkup is not as full as I would like.  Specifically, I think it should mention:
	-- if we means "last-hop" headers or "first-hop" headers.  This becomes interesting in the case of a portal A re-serving portlets up as WSRP services to be consumed by portal B, which in turn is embedding them in a user's page.  Should the transportHeaders argument have the headers from the first straight HTTP hop from the user to portal B or the HTTP (or SOAP?) headers in the hop from portal B to portal A?
	-- should hop-by-hop HTTP headers be taken out?  what about headers that could compromise the security of the serving portal (like Cookie or Authorization)?

(18)  I'm confused about the use of modes.  As written right now, the Consumer passes the mode to the Producer on calls to getMarkup and performInteraction.  I think the spec intends that a portlet is always considered to be in one of the possible modes, but I don't think that the Consumer can always know the mode.  For example, say the user clicks "Edit" in the portal and the Consumer calls getMarkup with the EDIT mode.  Now, the user clicks a link in the page.  How does the Consumer know if the Producer transitions back to VIEW mode or not?  

It seems to me that we should think of things like EDIT and CONFIG as predefined resources that the Producer can serve up.  There will be only one "page" each that corresponds to EDIT, CONFIG, PREVIEW, etc., and not all calls to getMarkup should have a mode.  Does this make sense to folks?

(19)  I'm concerned by the URL rewriting token, wsia:QXqKYZJVUWj7G.  Although in theory this string is relatively uncommon, it has two problems for me:

	(1) it will confuse users of the spec, as its name does not make its function clear.
	(2) once we choose it as a special token, we dramatically increase the chances that the token will appear in documents.  The WSIA/WSRP spec itself will not be able to be used as portlet content, for example.

Is there any way we could use escaping techniques to facilitate using a token that has a more clear name?  In languages like HTML that will have to be escaped in the SOAP response, doesn't it make more sense to use XML tags?

(20)  I haven't followed the Markup Committee very closely, and I found the section on both Producer & Consumer URL Writing confusing.  The questions I have are:
	-- What is the exact syntax of a template for Producer URL Writing?  I think it would be very useful to have a BNF grammar here to make sure that we all agree what the syntax is.  Is the following a correct interpretation of the spec?
	
	WSIAProducerURLTemplate = (Text* ReplacementToken*)*
	Text = <any UNICODE character except '{' and '}'>
	ReplacementToken = '{' ParameterName '}'
	ParameterName = 'sessionID' |
			'navigationalState' |
			'clientParameters'
	
	-- Similarly, is the following a correct BNF for Consumer URL Writing?
	
	WSIAConsumerURLTemplate = ConsumerURLBeginToken NameValuePairList ConsumerURLEndToken
	ConsumerURLBeginToken = 'wsia:QXqKYZJVUWj7G?'
	ConsumerURLEndToken = '/wsia:QXqKYZJVUWj7G'
	NameValuePairList = NameValuePair ('&' NameValuePair)*
	NameValuePair = NavigationalStateNameValuePair |
				SessionIDNameValuePair |
				EntityModeNameValuePair |
				WindowStateNameValuePair |
				URLNameValuePair |
				TokenNameValuePair |
				URLTypeNameValuePair |
				ConsumerResourceTypeNameValuePair
				SecureURLNameValuePair |
				RewriteResourceNameValuePair

	NavigationalStateNameValuePair = 'wsia:navigationalState' '=' Value
	SessionIDNameValuePair = 'wsia:sessionID' '=' Value
	EntityModeNameValuePair = 'wsia:entityMode' '=' EntityModeValue
	WindowStateNameValuePair = 'wsia:windowState' '=' WindowStateValue
	URLNameValuePair = 'wsia:url' '=' URI
	TokenNameValuePair = 'wsia:token' '=' Value
	URLTypeNameValuePair = 'wsia:urlType' '=' URLTypeValue
	ConsumerResourceTypeNameValuePair = 'wsia:consumerResourceType' '=' ConsumerResourceValue
	SecureURLNameValuePair = 'wsia:secureURL' '=' BooleanValue
	RewriteResourceNameValuePair= 'wsia:rewriteResource' '=' BooleanValue

	URLTypeValue = 'Action' | 'Render' | 'Resource' | 'Namespace' | 'ConsumerResource'
	EntityModeValue = 'EDIT' | 'VIEW' | 'CONFIG' | 'HELP' | 'PREVIEW' | Value
	WindowStateValue = 'MINIMIZED' | 'MAXIMIZED' | 'NORMAL'
	ConsumerResourceValue = 'OK_ICON' | 'OK_TEXT' | 'CANCEL_ICON' | 'CANCEL_TEXT' | 'INFO_ICON' | 'INFO_TEXT' | 'WARNING_ICON' | 'QUESTION_ICON'
	BooleanValue = 'true' | 'false'
	Value = <any text without substring '/wsia:QXqKYZJVUWj7G' or 'wsia:QXqKYZJVUWj7G?'>
	
	-- Finally, exactly what parameters of which calls in the interface are Producer URL writing templates sent on?  I think we should mention that in the Consumer URL Writing section.

Cheers,
Sasha.


-----Original Message-----
From: Rich Thompson [mailto:richt2@us.ibm.com]
Sent: Friday, August 30, 2002 10:19 AM
To: wsia@lists.oasis-open.org; wsrp-interfaces@lists.oasis-open.org
Subject: [wsia] [wsrp-interfaces] Draft spec v0.5



The doc file has now grown to 11MB ....

(See attached file: Draft Spec v0.5.ZIP)