OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

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

Thanks ... comments/questions in-line in this color.


"Clinton Davidson" <Clinton.Davidson@plumtree.com>

05/20/05 06:54 PM

Rich Thompson/Watson/IBM@IBMUS
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.

[1] http://www.w3.org/TR/xmlschema-1/#xsi_type

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]