RE: [wsrp-wsia] WSRP v.90 Technical and Editorial Comments

wsrp-wsia message

Subject: RE: [wsrp-wsia] WSRP v.90 Technical and Editorial Comments

From: Eric VanLydegraf <ericv@kinzan.com>

To: 'Michael Freedman' <Michael.Freedman@oracle.com>,wsrp-wsia <wsrp-wsia@lists.oasis-open.org>

Date: Thu, 23 Jan 2003 17:08:24 -0800

-----Original Message-----
From: Michael Freedman [mailto:Michael.Freedman@oracle.com]
Sent: Thursday, January 23, 2003 1:55 PM
To: wsrp-wsia
Subject: [wsrp-wsia] WSRP v.90 Technical and Editorial Comments

Rich,
I agree with Alejandro that you have done a fantastic job of evolving what was once an unwieldly specification into a tight coherent document. Good job and thanks.

[Eric VanLydegraf] Here Here.

The following are the items I noted during my latest review of version .90. The comments are separated into two sections, each ordered from the front of the document to the back. The first section contains issues and comments concerning technical aspects of the specification. The second section contains issues and comments concerning editorial aspects of the specification. I apologize for duplicating others comments [if any] as I haven't been able to keep up with all the e-mail.

Technical Comments

Section: 5.1.10 Page/Line: 22/4 Requestedby: Michael Freedman Old text: [R] string markupType Proposed text: [R] string markupTypes[] Reasoning: To reduce verbosity shouldn't we allow a portlet to define the N markup types for which the remainder of the structure applies? Or do folks think that this is such a rare case that not dealing with an array is a better form?
Section: 5.1.10 Page/Line: 23/20 Requestedby: Michael Freedman Old text: Proposed text: Issue: Our description/support for secure communication seems weak. In many places we tie together into a single boolean secure comunication between the client and consumer as well as secure communication between the consumer and the producer. Why do we do this? Do we really allow a Producer to offer both secure and non-secure ports at the same time? What is this use case for this? If so shouldn't GetServiceDescription return a boolean field indicating which should be used? Or are we expecting the register call to throw a fault indicating secure access is required? I.e. if we believe there is a use case for supporting both ports and transitioning between them [in a manner that is tied to the client]I think I understand this field but then aren't we missing a simple way to indicate all communication between the consumer and producer should be secure regardless of the communication between the client and the consumer?
Section: 5.1.17 Page/Line: 26/37 Requestedby: Michael Freedman Old text: none Proposed text: add a new field [O] boolean requiresSecureCommunication Reasoning: This field indicates whether all calls between the consumer and the producer must use the secure ports. Default would be false. We need a convenient way for a Consumer to know how to establish/continue communication with a Portlet for all calls.
[Eric VanLydegraf] If a Producer only declares non-secure or secure SOAP endpoints, that in itself takes care of one or the other, if both are supplied and the Producer is interested in the mixed secure transport style than we need to workout how that works just as you mentioned in the previous comment.
Section: 5.1.20 Page/Line: 29/3 Requestedby: Michael Freedman Old text: Faults: Security.Accessdenied, Security.InvalidUserCategory ... Proposed text: Remove AccessDenied, InvalidUserCategory, InconsistentParameters, AuthenticationFailure, and MissingParameters. Reasoning: None of these faults appear to have meaning in the conetxt of a getServiceDescription call.
[Eric VanLydegraf]
[Eric VanLydegraf] MissingParameters may apply as RegistrationContext could be null, but the Producer may requireRegistration=true.
Otherwise I agree with your list.
Section: 6.1.2 Page/Line: 30/27 Requestedby: Michael Freedman Old text: Proposed text: add a secureConsumerCommunication boolean field Reasoning: How does a Producer determine they were called via a secure channel? I.e. does JAX-RPC and other webstacks provide the equivalent of an isSecure() call or do we have to pass this information? [Eric VanLydegraf] This is always a problematic area, the security infrastructure should provide the security context, aka the transport is the only one that really knows, having anybody state the security setting is unverifiable information which defeats itself as far as security is concerned. The isSecure() is a good example of the infrastructure providing the information, as it does know exactly how the request was received. The web stacks will have to do the same thing or some other network or sofware infrastructure will have to enfoce the security requirements, because by the time the SOAP endpoint hands off the request it is too late.
Section: 6.1.5 Page/Line: 32 Requestedby: Michael Freedman Old text: Proposed text:
Reasoning: How do these values relate to the Portlet's needsSecureCommunication flag? I.e. are subsets of these NIL depending on whether the needsSecureCommunication is none or always? If so don't we need to rework the meaning of defaults? If not how does the Consumer reconcile the Portlet flag and the URLs it writes?
Section: 6.1.5 Page/Line: 32/18 Requestedby: Michael Freedman Old text: nameSpacePrefix Proposed text: remove this field
Reasoning: We intend to allow portlets to cache this structure on a session basis. This field appears to break this -- i.e. its value is related to the consumer instance of the portlet not the portlet instance itself. I suggest we just direct folks to use the portletInstanceKey in RuntimeContext. We should also require this later be passed when templates are required to be passed.
Section: 6.1.8 Page/Line: 33/25 Requestedby: Michael Freedman Old text: [R] boolean secureClientCommunication Proposed text: move this field to RuntimeContext
Reasoning: This information is likely as important to action handlers. It seems better suited if carried by the RuntimeContext vs. the MarkupParams.
Section: 6.1.8 Page/Line: 33/28 Requestedby: Michael Freedman Old text: [R] string markupCharacterSet Proposed text:[R] string markupCharacterSet[]
Reasoning: This provides HTTP equivalent function. Also, JSR 168 supports API for aquiring more then 1 character set.
Section: 6.1.15 Page/Line: 39/9 Requestedby: Michael Freedman Old text:[O] NamedString mimeHeaders[] Proposed text: [O] NamedString mimeAttributes[] Reasoning: We have avoided using the term Headers elsewhere in the specification [i.e. clientData field in MarkupParams]. Shouldn't we avoid it here as well?
[Eric VanLydegraf] ? mimeValues
Section: 6.1.16 Page/Line: 39/22 Requestedby: Michael Freedman Old text: [R] string interactionState Proposed text: [O] string interactionState Reasoning: Why is this a required field. I.e. why pass "" when there is no state?
Section: 6.2.1.2 Page/Line: 40/31 Requestedby: Michael Freedman Old text: When the MarkupParams structure supplied for generating the markup changes, the Consumer MUST treat the cached markup as if the expires duration had already elapsed. Proposed text: When the MarkupParams structure supplied for generating the markup changes, the Consumer MUST treat this as a cache miss. It may choose to auto-expire the entry. Reasoning: The old text implies only piece of content is cached per Portlet. The new wordign tries to avoid this.
Section: 7.2 Page/Line: 51/11 Requestedby: Michael Freedman Old text: Proposed text: Remove Security.AccessDenied and Security.AuthenticationFailure faultsReasoning: They don't seem to be appropriate. [Eric VanLydegraf] I would push it to transport level (e.g. HTTP 401 Error for Consumer failing to authenticate to Producer)
Section: 7.3 Page/Line: 51/27 Requestedby: Michael Freedman Old text: Proposed text: removeSecurity.AccessDenied, Security.AuthenticationFailure, Security.InconsistentParameters faults
Reasoning: They don't seem to be appropriate.
[Eric VanLydegraf] same as previous - push to transport.
Section: 10.3 Page/Line: 67/2 Requestedby: Michael Freedman Old text: Proposed text: Reasoning:This section says the Consumer is required to remove the namespace encoding even from HTML form fields. Though we discourage its use, Consumers will have to parse the form field names anyway just for the rogue portlet. This impacts performance. Anyway we can "prohibit" its use in form fields -- maybe by telling the Producer that the Consumer won't remove these prefixes?

Editorial Comments

Section: 5.1.1
Page/Line: 19/20 Requested by: Michael Freedman Old text: after "as part of containing data structures"Proposed text: "They are designed to communicate extended information between the Consumer and Producer". They aren't designed to communicate extended information in a roundtrip between either the Consumer itself or the Producer itself. I.e. neither the Consumer or the Producer should expect to receive the extensions back that it returned or passed in a structure in subsequent requests or responses."
Reasoning: We have a number of data structures that are repeatedly supplied to the Producer. We should make it clear that the Producer can't use the extensions field of these structures to pass/maintain state. Likewise for the Consumer.
Section: 5.1.11 Page/Line: 23/28 Requestedby: Michael Freedman Old text: This will require the Consumer format its URLS in a manner ... Proposed text: "If the Consumer chooses to accept/use this portlet, this will require ..." Reasoning: Make it clear in this description that Consumers can ignore such portlets.
Section: 5.1.17 Page/Line: 26/8 Requestedby: Michael Freedman Old text: [O] cookieProtocol Proposed text: Reasoning: This type isn't defined/described previously in this chapter. Shouldn't we add its description along with the rest?
Section: 6.1.1 Page/Line: 30/30 Requestedby: Michael Freedman Old text: A unique, opaque string the Consumer MAY ... Proposed text: A unique to the registrationContext, opaque string the Consumer MAY ... Reasoning: This isn't a globally unique string -- its merely unique to the registrationContext.
Section: 6.1.1 Page/Line: 30/31 Requestedby: Michael Freedman Old text: ... Consumer MAY supply as a reference to this use of the Portlet. Proposed text: ... Consumer MAY supply as a reference to its use of this Portlet. Reasoning: I found the first sentence confusing. I had trouble understanding whether this applied to the Consumer vs. the Portlet. I should probably take a grammar class -- but instead suggest replacing with "its" to make this clear.
Section: 6.1.1 Page/Line: 30/34 Requestedby: Michael Freedman Old text: Since this reference may be used as such a key, its length MUST be less than 256 bytes and Consumer SHOULD keep it as short as possible. Proposed text:Since this reference may be used as a key, its length MUST be less than 256 bytes. Consumer SHOULD keep it as short as possible.
Reasoning: I like it better ;-)
Section: 6.1.4 Page/Line: 31/19 Requestedby: Michael Freedman Old text: Note that any key caching systems use locate this markup ... Proposed text: Note that any key used by the caching system to locate this markup MUST include the MarkupParams structure that was current when the content was originally cached.
Reasoning: I like it better ;-)
[Eric VanLydegraf] I have suggested a fix for this one as well change request #16, but I like yours better so would promote this one over mine.
Section: 6.1.8 Page/Line: 34/42 Requestedby: Michael Freedman Old text: This field contains the opaque navigational state for this Portlet eitehr from the appropriate URL parameter or the most recently returned value for this End-User. Proposed text: This field contains the opaque navigational state for this portlet. To exist, navigational state must be set explicitly on each request either by setting its value upon return from a blocking action or in a non-blocking or render URL. Reasoning: Clarity.
[Eric VanLydegraf] Note CR#15 shows we have two ways in the spec for dealing with this, one is empty string default action and the other is keeping previous value around to pass along. I figure this will be a F2F discussion point.
Section: 6.1.8 Page/Line: 35/13 Requestedby: Michael Freedman Old text: An array of modes which the Consumer is indicating as available to be requested as a newMode in InteractionResponse. Proposed text: Current set of modes the Producer can request changing to. Can be used to specify a mode change either via an InteractionResponsde or within an URL written into the response markup. Reasoning: I like it better ;-)
Section: 6.1.12 Page/Line: 38/10, 13, 29 Requestedby: Michael Freedman Old text: Proposed text: remove sections describing sessionContext, portletContext, and markupContext Reasoning: They are no longer direct fields of this structure rather they are embedded in Interactionresponse.
Section: 6.1.16 Page/Line: 39/42 Requestedby: Michael Freedman Old text: [Mike ...] Proposed text: Common user agents (web browsers) encode posted data in the character set of the response that generated the page the form is on. As the Producer is ignorant of this encoding and the Consumer is required to encode passed parameters consistently (with the SOAP message), Consumers MUST ensure that form data is properly encoded when it is passed to the Producer. Reasoning: I figure we will debate whether this is a MUST or a SHOULD. Problem with SHOULD is that Producers can't be reliably written. Problem with MUST is the Consumer may not be able to always determine what character set they received from the user agent.
Section: 6.3.2 Page/Line: 41/15 Requestedby: Michael Freedman Old text: This operation also carries the semantics of blocking ... Proposed text: This operation is distinguished from performInteraction in that both the ... is blocked. Reasoning: I like it better ;-)
Section: 6.3.2 Page/Line: 41/41 Requestedby: Michael Freedman Old text: Since this operation .... Proposed text: Note, if the producer chooses to use the optimized form of this call and return markup directly care must be taken to ensure this Markup is generated with the navigationalState that is the result of executing the operation and not the navigational state that was passed to it. This ensures consistency when the optimization is not used and the Consumer recalls getMarkup after performBlockingInteraction returns. Reasoning: I like it better ;-)
Section: 6.10.2 Page/Line: 49/25 Requestedby: Michael Freedman Old text: These defintions suggest progressively restrictive levels of access to the potential functionality of the Portlet and are provided accordingly. Proposed text: These definitions suggest progressively restrictive levels of content and are provided accordingly. Reasoning: User Categories don't carry security semantics so mentioning access control is inappropriate.
Section: 10.2 Page/Line: 58/15 and throughout Requestedby: Michael Freedman Old text: interaction URLs Proposed text: portlet URLs Reasoning: We already define/use the term interaction. I seems inconsistently used here to refer to all type of URLs whether interaction URLs or render URLs or resources.
Section: 10.2.1.1.3 Page/Line: 61/21 Requestedby: Michael Freedman Old text: , the Consumer MUST a value of "". Proposed text: , the Consumer MUST supply a value of "". Reasoning: Clarity
Section: 10.2.2 Page/Line: 63/17 Requestedby: Michael Freedman Old text: Producers and Portlets ... may provide better page load performance to the End-User Proposed text: Remove this sentence or rewrite section to incorporate: "On the other hand, using Producer URL writing may have a negative impact on the cachability of content." Reasoning: Shouldn't encourage folks to use Producer URL writing for performance reasons as this may have the opposite effect.
Section: Appendix C Page/Line: 90/23 Requestedby: Michael Freedman Old text: Michael Freedman, Oracle Proposed text: Michael Freedman, Oracle Corporation Reasoning:Full company name unless all of us agree to a shorter form so we can stay multi-columned.