wsrp message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Re: My spec edits on the .9 draft
- From: Rich Thompson <richt2@us.ibm.com>
- To: wsrp@lists.oasis-open.org
- Date: Mon, 23 May 2005 10:35:39 -0400
Thanks ... comments/questions in-line
in this color.
Rich
"Clinton Davidson"
<Clinton.Davidson@plumtree.com>
05/20/05 06:54 PM
|
To
| Rich Thompson/Watson/IBM@IBMUS
|
cc
|
|
Subject
| My spec edits on the .9 draft |
|
My 2 cents. Disregard what you please. Most
are edits, a few are errors.
Line 308: Why do we call service description
self description? I realize it makes more sense here, but all the other
interfaces go by their actual names.
<rt> I had noticed this
not too long ago as well, but was absorbed in another task and so didn't
look hard at it. Unless someone objects, draft 10 will change this so that
the interfaces are consistently described in this introductory section
using the terms from their portType names. </rt>
Line 316: Enduing vs persistent. Do you want
to preface enduring with an explanation of why we use the new term? Or
just reference section 3.4?
<rt> Adding a forward reference
to 3.7 ... enduring state rather than enduring lifecycle. I am also adding
a few additional words to 3.7 to refer back to the lifecycle definition
in 3.4 and to lease expiration being a possible reason for the explicit
discard.</rt>
Line 367: XForms- can XForms even be used?
I thought that XForms required using the <head> element- as we don’t
have the ability to specify that content goes into the head element, has
anyone verified that xforms will work? What happens when there are multiple
xforms on a page, as there is only one head element?
<rt> Currently using XForms
would rely on the processor not enforcing the requirement that the data
model and constraint definitions live in the head. XForms has a means of
naming these items such that our standard namespacing considerations can
make them unique (even against multiple instances of the same portlet),
much as for scripts. It would be interesting to know if anyone has tested
using XForms in a portlet ...</rt>
Line 363: In the sentence “In
addition, the Consumer needs to manage the processing of interactions with
that markup in order to properly correlate the interactions with the, potentially
stateful, environment that produced the markup.”,
how about using parens instead of commas?
<rt> ok</rt>
Line 393: Destruction of relationships. Maybe
we can add a sentence that the relationship can be ended either explicitly
(i.e. deregister) or on a scheduled basis (lifetime).
<rt> Adding a phrase saying
that the explicit ending could be related to lease expiration (i.e. the
lease expiration can trigger a cleanup, but hopefully on a delayed basis).</rt>
Line 471: Typing information. You took out
either, but the sentence sounds better with ‘either’ and another ‘or’:
The preferred means for this typing
information includes using the schema defined[1]
“type” attribute to reference the correct schema on each such extension
element, and use of either the Producer’s WSDL (default), or the WSRP
defined “extra” namespace, or a “schemaLocation” attribute as per standard
schema usage to declare the details of all non-simple types.
<rt> ok</rt>
Line 496 reads “The registrationHandle
is created and destroyed using either in band mechanism, i.e. by declaring
support for the Registration
portType, or by out of band mechanism…” Does “an in band mechanism”
and “an out of band mechanism” sound better?
<rt> I think it would be
"the in band ... or an out of band" as there is only one in band
mechanism, but I agree that this makes it more readable.</rt>
Line 503: Describing how the portlet
scope is encapsulated in the registration scope. What if there was no registration?
Is it worth mentioning?
<rt> Adding the phrase ",
if one exists". If we think we should define the encapsulating scope
for when there is no registration, the definition should be careful to
only apply from the Consumer's perspective. One example I could imagine
would be where the Producer scopes such a situation using the Consumer's
security credentials ... from the Consumer's perspective things are scoped
at the Producer level while the Producer is actually enforcing that only
the one Consumer can access those cloned portlets.</rt>
Line 507 reads The Producer optionally
exposes this scope [portlet scope] by declaring support for the PortletManagement
portType. My (possibly incorrect) understanding is that portlet scope is
initiated when the portlet is cloned, either implicitly or explicitly,
and that an implicit clone does not require the PortletManagement portType.
<rt> You are correct at
a technical level, but any compliant Producer who returns an implicit clone
is required to support the PortletManagement interface (allows for destroyPortlets).</rt>
Line 518: Resources. My concerns
are first, to provide an example so this does not sound so abstract, second,
the possible confusion with getResource.
<rt> Adding "(examples
include a portlet, which is referenced via a portletHandle)"
to the end of the first sentence.</rt>
Line 553 reads “It is always the
Consumer’s responsibility to supply this type of state and incorrect results
will frequently result if a Portlet stores supplied values within one of
the types of state it manages. “ Does this mean something like “As it
is always the Consumer’s responsibility to supply this type of state,
the Portlet should not store Public Parameters in session state or navigational
state.”?
<rt> or in a db or any other
state mechanisms (e.g. pushing it to the browser in hidden formfields,
etc)</rt>
Line 619: when you state that distributing
events is entirely optional, where do we talk about “graceful degradation”?
<rt> Does adding "This
enables Consumers to provide coordinated cross-portlet response to the
End-User’s interaction while providing the equivalent user experience
as WSRP v1 for those Consumers not supporting event distribution."
help?</rt>
Line 795 reads “We RECOMMEND extensions
be of type xsd:string
(where xsd stands for http://www.w3c.org/2001/XMLSchema),
a type from the WSRP-defined “extra” namespace or be of a type
defined in the Producer’s WSDL as this enables Consumers to prepare an
appropriate serializer/deserializer.” How about “We RECOMMEND extensions
be of type xsd:string
(where xsd stands for http://www.w3c.org/2001/XMLSchema),
or by of a type from the WSRP-defined “extra” namespace,
or be of a type defined in the Producer’s WSDL as this enables Consumers
to prepare an appropriate serializer/deserializer.”
<rt> ok ... but with a spelling
correction to "be"</rt>
Line 810 reads “Overlap with the
fields defined in the containing structure SHOULD be voided.” I assume
you mean avoided. In the same paragraph, should we have a section
in the primer or faq on “highly typed” and “aids deserialization”?
All we would need is an explanation that the any type by itself
is difficult to work with.
<rt> good catch!!!!! Agreed
on the value for a Primer section, but I'm not sure this rises to the level
of needing an entry in the FAQ ... overloading it decreases its value.</rt>
Line 965: about naming events hierarchically-
would it be too obvious to mention that you are referring to the local
part of the qname?
<rt> clarity is a good thing</rt>
Line 997 reads “We would encourage
those adding values to this extensible set use qualified names to reduce
instances of name clashes:” How about “to use”?
<rt> and dropping "would"</rt>
Line 1029 reads “The PortletDescription
structure contains a set of fields that provide the metadata to describe
the Portlet as well as any clones of the Portlet.
” If a reader did not know better,
they could take this to mean that the clone has the same metadata as the
pop.
<rt> That does come up as
a question from time to time. I can imagine a dynamic Portlet whose PropertyDescriptions
might vary from the POP, but those don't appear directly in the PortletDescription.
Can anyone think of a use case for the PortletDescription varying?</rt>
Line 1453: on namespacePrefix and
portletInstanceKey- my understanding was that namespacePrefix was less
unique than portletInstanceKey. In our world, the namespacePrefix only
needs to be unique to the aggregating page; the portletInstanceKey needs
to be unique in the registrationContext.
<rt> I inserted the comment
because developers might wonder why we have both. While your comment is
the normal case, consider when two views onto the same portlet instance
are on the page (shared session, but unique navState). These would share
a portletInstanceKey, but need distinct namespacePrefixes.</rt>
Line 1490 reads “Note that such
uses can span multiple starting and stopping cycles of the Consumer and
therefore this state MUST be persisted by the Consumer until successfully
invoking destroyPortlets with the related portletHandle.”
Maybe …”until destroyPortlets is successfully invoked with the related
portletHandle.”?
<rt> That sentence received
a lot of word smithing in the v1 days, but leasing also comes into play
now. Would people agree to "Note that such uses can span multiple
starting and stopping cycles of the Consumer and therefore this state MUST
be persisted by the Consumer until the Portlet’s lifecycle ends via the
destroyPortlets operation or the expiration of a lease."?</rt>
Line 1596: You mention MarkupParams
for ClientData, but I imagine that this has already been edited, given
your previous email.
<rt> That definition is
up for comments on another email thread.</rt>
Line 1643 reads “The Consumer
can supply this information based on the setting the End-User has requested,
but is encouraged to also take into account the locales the PortletDescription
declared were supported for the mime types being requested.” Does this
mean that that if locales are specified for all matching mime types, and
the End-User locale is not included, that the Consumer should return an
error to the end-user without calling the Producer? This is what I would
assume from reading MimeType, i.e. locales specified = only these locales;
no locales specified = maybe all are supported.
<rt> Consumer choice ...
could directly return error markup to the user for guidance or could call
the Portlet requesting a locale the Portlet has not said it supports. In
the later case, the Portlet could either do a best effort, return a fault
or request guidance from the user.</rt>
Line 1743: markupBinary. Maybe
this belongs in the primer or the faq, but what to do with binary is slightly
confusing. At first glance a developer would think that they would call
response.setContentType(mimeType) and then just write the markupBinary
to the ServletOutputStream. But requiresRewrite implies that the developer
should transform the markupBinary to a string using the encoding on the
mimeType, and then rewrite it. Or is that too much of an implementation
detail?
<rt> Likely will be a Primer
topic related to using MTOM.</rt>
Line 1747 on locales- if the Producer
is free to return markup in another locale, should a corresponding note
be made in MimeType?
<rt> Do you mean that the
mime type is not required to be one of the requested types?</rt>
Line 1791 on Event type- we may
want to mention why EventPayload is optional, as in the case of the eventHandlingFailed
event.
<rt> Would "One example
of when this field might not be included is when the event is simply a
signal and the event’s name thereby carries all of the semantics of the
event." help?</rt>
Line 2075 reads “The Online
structure is used to describe the various phone contact information.”
I assume you mean “Web oriented contact information”, as you say in line
2116.
<rt> Cut and paste is such
a wonderful thing :} </rt>
Line 2120 on UserContext reads
“Note that this does not carry user credentials (e.g. userID / password)
as quite flexible mechanisms for communicating this information are being
defined elsewhere (e.g. WS-Security (see section 3.1.2) defines how to
carry User Information in a SOAP header).” The problem is that we took
WS-Security out of the list of emerging specifications.
<rt> updated to reference
3.1.1 ... it was moved to the existing standards section.</rt>
Line 2417 in local state table-
the comment reads “With Producer side state, the session handle offers
ability to store information without impacts message size to Consumer.”
Maybe “With Producer side state, the session handle offers the ability
to store information without increasing the message size to the Consumer.”
The same sentence is duplicated with getMarkup.
<rt> ok</rt>
Line 2439: (1) Is there ever a
case where the PortletDescription returned by getPortletDescription is
the same as the PortletDescription from getServiceDescription? (2) Should
we add a section to the primer or faq for when an implementation may cache
PortletDescription?
<rt> Interesting place to
think about this comment. I could see this as a lower priority Primer section.</rt>
Line 2458: on wsrp:edit. Should
we mention that changing state is not limited to wsrp:edit?
<rt> good idea</rt>
Line 2677 in deregister: uses a
InvalidRegistration instead of an InvalidRegistration
<rt> thanks!</rt>
This was exhausting, but I wanted
a better understanding to put in v2 features of the faq. I can’t imagine
having to write the spec itself.
-Clinton
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]