WSRP 2.0 review

[Michael Freedman <michael.freedman@oracle.com>]

I have reviewed the current draft of the WSRP 2.0 specification and am 
attaching the issues list I generated.  Its broken into three sections:  
Editorial Changes -- comments on recrafting wording or fixing errors, 
Discussion Issues/Change Requests -- items I would like to discuss with 
the committee to either modify semantics or clarify my understanding, 
and Original Issues -- those issues that I think still remain in the 
document from the original list I put together in December.  Enjoy.
     -Mike-

Title: WSRP 2.0 issues list

Editorial changes:

1. Page 8 lines 4-6:  Clean up references to "both committees" as the WSIA reference has been eliminated.
2. Page 8 line 14: "However this description ...".  What does description refer to?  The previous paragraph or this specfiication?  How about "There are additional important scenarios that motivate WSRP that aren't related to Portal servers.  A number of these have been defined by the the Web Service for Interactive Appplications (WSIA) These use cases have also been instrumental in shaping WSRP."
3. Page 9 section 1.2.2:  Extend the list to describe the new interfaces.
4. Page 13: section 3.4 Lifecycles:  Need to rework description now that we support leasing as there may not be as much difference between persistent and transient.
5. Page 14: section 3.6:  In discussion of Transient state probably need to add a thrid type -- our public parameters.
6. Page 15: section 3.11, line 33:  "In addition, the Consumer can selectively distributing event, ...
7. Page 15: section 3.11 , line 46:  New paragraph for: "Examples of when the first two steps might not be used include:"?
8. Page 17: section 4: Interface Overview:  line 37:  register() method signature doesn't match that of one in section 7.2 (page 65).  The later has a LifeTime parameter
9. Page 25 line 51: "array, the information such events contain will not [be] distributed by Consumers requiring explicit wiring of events."  Though you might just consider rewording altogether to avoid question of whether you are referring to the payload or the event itself. "array, this may limit use as many consumer may not be able to process and distribute events that haven't been previously published.
10. Page 25: line 20: PropertyDescription is referenced but not yet defined.  Should we move it before this section?
11. Page 31: line 31: TerminationTime should be terminationTime.
12. Page 45:Section 6.1.18: HandleEventsFailed:  "The HandleEventsFailed structure contains the [0 based] index of [the]event in the incoming events array that could not be processed fully by the Producer,"...
13. Page 52: line 45:  references the wsrp-preferOperation flag but I don't think this has been defined yet.  Either indicate explicitly where this flag resides or footnote it.
14. Page 63: section 6.11.2. "This is a Consumer generated event signals which the Consumer errors occurred while distributing events".    I can't make heads or tails out of this senetnce.
15. Page 72: line 15: "Whether [or] not a retry would likely succeed is unknown."
16. Section 9.2: starting at line 37:  "The supplied toUserContext...".  I suggest we change this to "The supplied toUserContext provides information concerning the End-User making the request to create the new copies in the toRegistrationContext."   Likewise change the fromUserContext description: "The supplied fromUserContext provides information concerning the End-User requesting the copy in the fromRegistrationContext."
17. Page 73: section 10 line 11.  Add a new last sentence: "Nor is the the Producer reconstituting the Portlets on the Consumer's behalf required to be the same Producer that provided the original representation."
18. Page 76 line 29 end of line.  Punctuate with a . not a ,
19. Page 76 line 39.  Add at end "This parameter only applies when the producer's response is not exporting by value.  Otherwise it is ignored".
20. Overall -- import/export/copyPortlet:  make descriptions of these very similar -- exportPortlets says things like the producer MUST return exactly one entry in its response for each entry in the request.  Make CopyPortlets consistent or remove.  Likewise sync description of failure reasons, faults, etc.
21. Page 74 line 10:  capitalize as follows: exportContext.
22. Page 77 line 38.  We need to complete the sentence to make it meaningful: "As a result, the responsibility to recover from any failures associated with the attempt to release artifacts."
    

Discussion Issues/Change Requests:

1. Page 10 Section 1.2.3: Description of Consumer -- I would like to extend/alter are description of the Consumer -- basically to move us to extend a notion of a consumer to those applications that view portlets as another type [albeit special] of view component in its toolset.  "A Consumer is an application that incorporates, in part or as whole, an intermediary function that communicates with presentation-oriented web services (i.e. Producers and the Portlets they host) on behalf of its users.  It gathers and aggregates the markup delivered by the Portlets and its other view components and presents this rendition to the End-User ..." and then leave the rest as is.   However when we get down to the next section [1.2.4] it would be better worded as "The main purpose of a Consumer acting as a content intermediary for various Producer/Portlets is the preparation and presentation of markup to an End-User...." leave the rest as is.
2. Interface organization:
1. I don't understand the logic for separating the Lifetime interfaces from their natural interfaces.  It would be okay if the natural interface were Lifetime independent -- but its not.  -- give us fewer ports/interfaces to deal with.
2. Does anyone [consumer or producer] use the PortletManagement Property interface?  This seems like it was a mistake.  Even if not it seems of least importance in PortletManagement Interface.  Can we move these methods to a new interface?  Can we talk about deprecating them in the future?
3. Let's move CopyPortlet and ImportExport back into the PortletManagement Interface.  PM is already an optional interface -- CopyPortlets/Import/Export are significantly more important to real consumer/producer portlet management then the property stuff ever was -- this will strongly encourage their implementation/support.  If we do this merely add UnsupportedOperation Fault which can be thrown to signify lack of support/implementation.
3. Types for Event payloads, public parameters, and registration xxxx:  We should have/use wording similar to extensions:  "The use of types defined within the WSRP extra namespace is encouraged as this increases the likelihood of the Consumer being able to serialize/deserialize the data in a useful manner.
4. Section 5.1.11: EventTypeDescription:  Does requiresSecureDistribution really mean requiresSecureTransport -- i.e. only that a secure transport mechanism must be used -- but not other security required?  I assume so, however I wonder if we need to adjust these names as it may be somwhat confusing in the future when security is better supported.
5. Section 5.1.12:  Should publicParameterDescriptions be of type ModelDescription not PropertyDescription?  If so need to move this type as well [see editorial comment #10]
6. Section 5.2: lines starting at 43.  Do the portletHandles have to reference POPs or can they reference cloned portlets?  I prefer POPs -- if so need to restrict this in the language.
7. Section 6.1.18: HandleEventsFailed type:  Should detail field really be an any?  Better to make a string and leave the any for the extensions?
8. Section 6.1.19: handleEventsResponseType:  Why does an event response return a redirect?  How does this impact event processing?
9. Naming inconsistency between copyPortlets and Import/Export:  CopyPortlet returns copySuccess/copyFailure fields with correpondingly named types.  Import/Export returns imported/exportedPortlets;importFailure/exportFailure with corresponding types.  We should reconcile.  
10. The description for wsrp-urlType = resource is written with an eye towards consumers that don't support calling getResource() -- i.e. use of wsrp-resourceID and the wsrp-preferOperation parameters hint [strongly] for using the method call but don't require it -- however is this really true.  Can't the Producer merely set wsrp-url to ""?  Or do we strongly discourage producers from doing so.  We might need to be more explicit as to our intentions here.
    

Original Issues list raised in December that I don't know the resolution/reason for:

1. HandleEvent:  should it take InteractionParams?  What is the reason for this vs. this is only sent to performBlockingInteraction?  Looks like all its used for is to pass the portletStateChange flag.  Should we put this in something else like EventParams?
2. PortletLifetime operations.  Should they take a UserContext to be consistent?  Or do we have the whole UserContext discussion and exclude from existing APIs because not used to carry "application role" information?
3. Lifetime structure:  what is the units for refreshDuration; msecs, secs? Is it obvious from dateTime type?
4. I thought we decided that HandleEvents couldn't cause a redirect?  Or did we just decide its up to the consumer to honor whichever redirect they receive?
5. "While the Consumer MAY invoke handleEvent() multiple times for any one portlet while preparing to gather markup, it MUST NOT invoke handleEvent() an additional time while the portlet is already processing an event for the same End-User."  This implies the consumer can't implicitly timeout an event call without dropping subseqent events from being distributed.  Is this what we want?