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

 


Help: OASIS Mailing Lists Help | MarkMail Help

icom message

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


Subject: RE: [icom] Article


Eric,

On Wed, 2011-01-19 at 12:48 -0800, Eric Chan wrote:
> Hello Patrick,
> 
> The article is to be posted on java.net to accompany a new project for ICOM JPA framework. The audience is developers who will extend the source code for ICOM JPA framework. Considering the amount of time and resource a developer has to put into understanding the source code design and data model, the amount of technical detail in this article is minimal.
> 

OK, let me try again.

It is *not* a question of the content being technical. 

Many articles have technical content and are shorter than this
"article." 

The problem is that at least in my view, the article doesn't explain the
model to its best advantage.

For example, look at the Overview of ICOM, first paragraph:


> ICOM specification defines a class called Entity which is the super
> class of any class that supports a persistent identifier, a change
> token for optimistic locking, and an access control list. The object
> identifier and change token are annotated, respectively, by
> “javax.persistence.Id” and “javax.persistence.Version,” matching the
> ICOM concept of Entity with the JPA concept of Entity. ICOM Entity has
> an extra dimension for access control list, which together with JPA Id
> and Version, defines a unit of persistent information for concurrency
> and access control. The generation of object identifiers is
> implementation dependent; however, ICOM recommends that the object
> identifiers should be globally unique to support permanent references
> to the entities that may migrate amongst interoperable ICOM
> repositories. An object identifier is read only (immutable) once it is
> assigned and should never be duplicated or re-used for more than one
> object. The UML diagram in Figure 2 depicts the Entity class,
> properties, and cardinality of the properties. Entity’s properties
> include name, created by, creation date, last modified by, last
> modification date, owner, parent, attached markers, category
> applications, tag applications, and access control list.

**comments**

Here is how I would capture all that technical information:

The Entity class is the super class of any class that supports a
persistent identifier, a change token for optimistic locking, and an
access control list. 

JPA-Note: The object identifier and change token are annotated,
respectively, by “javax.persistence.Id” and “javax.persistence.Version,”
which maps the ICOM and JPA concept's of Entity together. 

**I am not sure that annotation "maps the concepts together but leaving
that aside for the moment.**

ICOM Entity has an AccessControlList, which together with
“javax.persistence.Id” and “javax.persistence.Version,” defines a unit
of persistent information for concurrency and access control. 

**recasting this entirely**
The generation of object identifiers is implementation dependent;
however, ICOM recommends that the object identifiers should be globally
unique to support permanent references to the entities that may migrate
amongst interoperable ICOM repositories. An object identifier is read
only (immutable) once it is assigned and should never be duplicated or
re-used for more than one object. 
**/recasting this entirely**

The generation of object identifiers is implementation dependent, but
all object identifiers are immutable once assigned, should be unique
within the implementation. 

**I am not sure what it means to say: "should never be duplicated or
re-used for more than one object." Usenet for example eventually,
forgotten how often, recycles identifiers. Unless we are going to say
shall or simply post a warning note, not sure it is worth the effort.**

The UML diagram in Figure 2 depicts the Entity class, properties, and
cardinality of the properties. 

**cut** Entity’s properties include name, created by, creation date,
last modified by, last modification date, owner, parent, attached
markers, category applications, tag applications, and access control
list.**/cut**

They have the diagram, do we need to repeat the listing? 

Copying only part of the following paragraph to illustrate a particular
point:


> Here we explain the usage of each of the properties of Entity shown in
> Figure 2. ICOM relies on object identifier for persistent
> identification of an entity and allows the name string of the entity
> as an optional property. The actor who creates an entity is
> represented by the created by attribute. The created by and creation
> date attributes are set by the system and cannot be changed once they
> are set, hence created by and creation date are read-only attributes
> for applications. The last modified by and last modification date
> attributes can be updated by applications although ordinarily these
> attributes should be set by the system. The owner of an entity can be
> either a single actor or a group of actors. 

Compare that partial paragraph to Figure 2 and tell me what is
different? 

Ah, we don't use the same names for properties in the prose as we do in
the diagram. Your switching context issue. 

createdBy becomes created by attribute

creationDate becomes creation date

lastModificationDate becomes last modification date

All of which are understandable, but why the change? 

We have names for all these things, names which technical people should
be comfortable with, so why not use those names? 

If we repeat the names at all. 

I think I have captured all the "technical" content but in such a way
that it flows from one part to another and the reader can distinguish
the JPA portions from the ICOM portions. 

I have another suggestion, quite possibly a bad one.

Why not produce an annotated version of the standard document itself? 

Have the "gist" article as we were talking about it and a separate
document/article, whatever, that is a JPA annotated version of the
standard document? 

That is we insert where appropriate only the additional JPA material.

*And* we can insert additional explanatory material, examples, etc., all
the stuff that should not be in a standards document.

That way technical people have the standard as well as the explanatory
material. 

How does that sound?

Hope you are having a great day!

Patrick

> We may also publish a concise version to give the gist of the project and refer the readers to the longer version.
> 
> Thanks,
> Eric
> 
> 
> -----Original Message-----
> From: Patrick Durusau [mailto:patrick@durusau.net] 
> Sent: Wednesday, January 19, 2011 5:29 AM
> To: icom
> Subject: [icom] Article
> 
> Eric,
> 
> I have what may seem like a silly question but here goes:
> 
> Who is the intended audience for the article?
> 
> I ask because the long stretch of UML diagrams makes me suspect it isn't
> managers or users. 
> 
> Starting with figure 2 where *the usage of each of the properties* is
> explained.
> 
> Even if the purpose of the article is to interest even information
> architects or programmers in the JPA/ICOM framework, it doesn't have to
> explain every property or its usage. 
> 
> Sure, a reference manual or standard has to do that, but not an article
> meant to interest others in its use.
> 
> A more compelling case could be made with fewer diagrams.
> 
> For example, surely there are use cases that Oracle is already working
> on using ICOM. Where integration has resulted in a benefit to the
> organization.
> 
> Why not start with a very high level view of that problem and walk
> through a very simplified version of ICOM?
> 
> For example, Entity represents XXX and just mentioned that all entities
> have access controls (for details see the ICOM standard), etc. 
> 
> I would suggest also block diagramming, at a fairly high level, what JPA
> brings to ICOM.
> 
> Hope you are having a great day!
> 
> Patrick
> 




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