wsrp-wsia message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [Elist Home]
Subject: [wsrp-wsia] WSRP v.90 Technical and Editorial Comments
- From: Michael Freedman <Michael.Freedman@oracle.com>
- To: wsrp-wsia <wsrp-wsia@lists.oasis-open.org>
- Date: Thu, 23 Jan 2003 13:55:25 -0800
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. 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.
- 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.
- 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?
- 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?
- 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.
- 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.
- 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 ;-)
- 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.
- 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