[oslc-core] Guidelines for specifying future-proof resources/capabilities
Steve K Speicher
sspeiche at us.ibm.com
Wed May 12 09:24:44 EDT 2010
I think the key difference here is that this shape definition and exposed
interface is the *integration* interface to the CM service provider. It
should not (nor could it completely) expose its constraint system on the
rules needed to be satisfied by a client to create or transition the state
of a change request. I do not see it as that our goal is writing
generic clients but solving integration scenarios. Some burden needs to
be placed on the service provider as it is the only one who best knows how
to deal with some of the system constraints.
Thanks,
Steve Speicher | IBM Rational Software | (919) 254-0645
> From: Nick Crossley/Irvine/IBM at IBMUS
> To: oslc-core <oslc-core at open-services.net>
> Date: 05/06/2010 04:00 PM
> Subject: Re: [oslc-core] Guidelines for specifying future-proof
> resources/capabilities
> Sent by: oslc-core-bounces at open-services.net
>
> But at least for CM, the spec cannot help! Most CM systems are
> highly configurable, so the set of required properties varies from
> site to site, not just between providers. A client wanting to
> create a change request needs to be able to discover the set of
> required properties in a particular installation - that is, if we
> are trying to allow for such generic clients. As in many other
> recent discussions, it all comes back to the scope of OSLC - what
> are we really trying to achieve?
>
> Nick.
>
> -----Arthur Ryman <ryman at ca.ibm.com> wrote: -----
> To: Nick Crossley/Irvine/IBM at IBMUS
> From: Arthur Ryman <ryman at ca.ibm.com>
> Date: 05/06/2010 12:42PM
> Cc: oslc-core <oslc-core at open-services.net>, oslc-core-bounces at open-
> services.net
> Subject: Re: [oslc-core] Guidelines for specifying future-proof
> resources/capabilities
>
> Nick,
>
> Perhaps the real point here is how much information we should try to put
> in the resource shape descriptions. In general, any operation on a
> resource will have a set of pre-conditions, e.g. that some properties be
> present or satisfy some condition. We could describe some simple ones in
> the shape, but at some point we'd have to tell consumers to read the
spec.
> Having a lot of variant shapes could get out of hand quickly.
>
> The shape should describe necessary, but perhaps not sufficient,
> pre-conditions. So in your multiple creation example, you could have a
> very generic shape with lots of optional properties, and the consumer
> would have to read the spec to determine which ones were required in any
> given state.
>
> Regards,
>
___________________________________________________________________________
>
> Arthur Ryman, PhD, DE
>
>
> Chief Architect, Project and Portfolio Management
>
> IBM Software, Rational
>
> Markham, ON, Canada | Office: 905-413-3077, Cell: 416-939-5063
> Twitter | Facebook | YouTube
>
>
>
>
>
>
>
> From:
> Nick Crossley <ncrossley at us.ibm.com>
> To:
> oslc-core <oslc-core at open-services.net>
> Date:
> 05/06/2010 01:34 PM
> Subject:
> Re: [oslc-core] Guidelines for specifying future-proof
> resources/capabilities
> Sent by:
> oslc-core-bounces at open-services.net
>
>
>
> I'm not sure it is a simple as that.
>
> For example, in Change, different properties of a change request
resource
> are required at different stages of its life cycle. Some are required
on
> creation, some are required in later states. Even the set required on
> creation can vary: one of my colleagues just described the way he needs
to
> describe required attributes during creation in Rational Change:
>
> In Change, we can submit new CRs to different states. Each state may
have
> different required attributes to create the CR. I think it would be
> modeled like this in OSLC 2:
>
> - Each state we can submit to has a different creationFactory URL
(e..g.,
> /oslc/crfactory/START_HERE2entered,
/oslc/crfactory/START_HERE2assigned).
> - Each factory has as associated shape URL.
> - Requesting the "shape" returns XML describing how to POST to that URL
> including an element for each attribute that can be submitted.
> - Each attribute description has an "occurs" element. For required
> attributes, this would be set to "exactly-one".
>
> Many of these required properties are still editable - they are not
> system-supplied. For example, the name of the person to whom the change
> request is currently assigned is modifiable, but is required when
creating
> a CR in the assigned state.
>
> Note that the shape for query has to be different from both of the
shapes
> he described above - since life cycles and process requirements can
change
> leaving older objects with a slightly different set of properties, and
> since objects can change state allowing some properties to be deleted,
> there can be very few "exactly-one" required attributes for a query
shape
> - almost all would have to be optional.
>
> Nick.
>
> -----oslc-core-bounces at open-services.net wrote: -----
>
> To: Dave <snoopdave at gmail.com>
> From: Arthur Ryman <ryman at ca.ibm.com>
> Sent by: oslc-core-bounces at open-services.net
> Date: 05/06/2010 06:30AM
> Cc: oslc-core <oslc-core at open-services.net>,
> oslc-core-bounces at open-services.net
> Subject: Re: [oslc-core] Guidelines for specifying future-proof
> resources/capabilities
>
> Dave,
>
> I think the spirit of REST is that you create via PUT or POST and that
GET
>
> is more or less the inverse of PUT. The only exception is that when you
> GET the resource, it may have acquired some additional properties, e.g.
> creator, creation date, an identifier, etc. The way I was distinguishing
> these in the EMS spec is via the editability of the property, not its
> occurrence. The properties that are maintained by the service are
> read-only and they should not be provided on creation since they are
> generated by the system. Normal properties are read-write. You could
also
> imagine write-once properties that you only set on creation and that
> cannot be changed later.
>
> Given that we can distinguish client-provided (read-write) versus
> system-generated (read-only) properties, then there should be no need to
> have different creation and query resource shapes.
>
> Regards,
>
___________________________________________________________________________
>
>
> Arthur Ryman, PhD, DE
>
>
> Chief Architect, Project and Portfolio Management
>
> IBM Software, Rational
>
> Markham, ON, Canada | Office: 905-413-3077, Cell: 416-939-5063
> Twitter | Facebook | YouTube
>
>
>
>
>
>
>
> From:
> Dave <snoopdave at gmail.com>
> To:
> oslc-core <oslc-core at open-services.net>
> Date:
> 05/06/2010 08:04 AM
> Subject:
> [oslc-core] Guidelines for specifying future-proof
resources/capabilities
> Sent by:
> oslc-core-bounces at open-services.net
>
>
>
> re: Specification versioning
>
> I'm still working representations today, but I've been thinking more
> about the guidance that we should provide in Core spec to help
> workgroups specify "future proof" resources.
>
> The rule
>
> * A new version of an OSLC specification is not allowed to
> introduce changes that will break old clients.
>
> The guidelines
>
> For OSLC workgroups, these are some guidelines to help you live with
> the above rule and specify OSLC resources that are as future-proof as
> possible.
>
> 1) Think you need a property but cannot agree on the value-type?
> This is a strong indication that you should not attempt to standardize
> on the property. Once decide on a value-type you are stuck with it
> forever. Wait until you have the scenarios or implementation
> experience needed to agree upon a value-type.
>
> 2) When introducing a new capability, e.g. a creation factory,
> query capability or delegated UI dialog; one that works differently
> than those specified in the Core spec or older versions of your own
> spec, you should create a new resource type to represent the service.
> This will enable old clients to continue to work against old services
> and new clients to work with your new capabilities.
>
> 3a) When defining resources, you are not allowed to remove, change
> the meaning or the value-type of any properties that you defined in
> earlier versions of the specification. You can add new properties but
> not change those that already exist.
>
> 3b) When defining resources, consider which ones are required to
> provided by clients at creation or update time vs. those which are
> required to be in representations returned by the server. When
> creating a new version of a specification: it's OK to relax
> restrictions on clients but it is not OK to add new required
> properties because that will break old clients.
>
> ISSUE: we should pick either 3a or 3b. At this point, I think 3b seems
> more reasonable and gives workgroups some more leeway in making
> changes, but...
>
> ISSUE: how can we enable 3b? Do we recommend that OSLC domains provide
> different shapes for creation vs. query? Do we require that domains
> specify two ""occurs" values for each property: oslc:creationOccurs
> and oslc:queryOccurs? Does this overlap with the oslc:queryable value
> that we discussed yesterday?
>
> I'd like to write this up (and the rest of the changes in
> http://open-services.net/bin/view/Main/OslcCoreMeetings04302010) this
> week, so any feedback, comments, suggestions, etc. you might share are
> all most welcome.
>
> Thanks,
> - Dave
>
> _______________________________________________
> Oslc-Core mailing list
> Oslc-Core at open-services.net
> http://open-services.net/mailman/listinfo/oslc-core_open-services.net
>
>
>
>
> _______________________________________________
> Oslc-Core mailing list
> Oslc-Core at open-services.net
> http://open-services.net/mailman/listinfo/oslc-core_open-services.net
> _______________________________________________
> Oslc-Core mailing list
> Oslc-Core at open-services.net
> http://open-services.net/mailman/listinfo/oslc-core_open-services.net
>
>
>
> _______________________________________________
> Oslc-Core mailing list
> Oslc-Core at open-services.net
> http://open-services.net/mailman/listinfo/oslc-core_open-services.net
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-core_open-services.net/attachments/20100512/918eb6cb/attachment-0003.html>
More information about the Oslc-Core
mailing list