[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: RE: [wsrp-wsia] WSRP v.90 Technical and Editorial Comments
-----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 CommentsRich,
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 faults
Reasoning: 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: remove Security.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.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC