Forum OpenACS Q&A: doc enhanced: Chapter 4: Data Models and the Object System

1: doc enhanced: Chapter 4: Data Models and the Object System

Posted by Simon Carstensen on 04/12/02 05:12 PM

Hi everyone,

I took some time this friday afternoon to enhance chapter 4 of the OpenACS 4.5 Developer Guide. Basically I have:

Done a search+replace, changing "PL/SQL" to "PL/pgSQL" and "Oracle" to "PostgreSQL".
Ported the PL/SQL syntax to PL/pgSQL syntax.
Added explanations for package_name and type_extension_table. Explanations for name_method and abstract_p are still missing. I was unable to find information on these, so can anyone please provide me with the definitions of these parameters?
and edited out a little text here and there.

I know this doesn't change the fact that the current object system documentation is too simplistic, that more examples and details need to be added to the current documentation, but I thought it would be a nice addition until better crafted documentation comes along.

Has anyone been assigned to porting the Object System documentation? If not, I'd be willing to take that upon me.

On a final note. Looking through various datamodels, I have found the naming scheme to be somewhat irregular. Perhaps this is the time, now that the documentation is being written, to decide on an official naming scheme for the datamodels (i.e. write new__foo_id instead of p_foo_id etc.)?

I hope this comes to some help - let me know what you think.

Regards,
Simon

2: Response to doc enhanced: Chapter 4: Data Models and the Object System (response to 1)

Posted by Don Baccus on 04/13/02 02:44 AM

Hmmm...of course we don't want to get rid of the Oracle version of documented queries because we support both RDMBSs.

Should we have two chapters, one PG and one Oracle, or just provide both examples embedded in the text?

As far as taking on the object system documentation - YES. I think folks would find this tremendously useful.

We more-or-less settled on "v_*" and "p-*" for variable and parameter names by convention in the PG version, but many of the SQL files you see were ported over by Dan Wickstrom using some scripts he wrote *before* that decision was made. It might be possible to make things consistent in the next release, but it's too late for 4.5 ...

3: Response to doc enhanced: Chapter 4: Data Models and the Object System (response to 1)

Posted by Simon Carstensen on 04/13/02 03:01 PM

"Should we have two chapters, one PG and one Oracle, or just provide both examples embedded in the text?"
Embedding Oracle and Postgres syntax side by side like the installation instructions for them are in the installation docs would make it hard to read and very long. I see 2 worthwhile options:
- Linking Oracle syntax under the Postgres code (seems like the majority of the people here is using Postgres, so I'm thinking it would make more sense embedding the Oracle syntax and not vice versa).
- Adding sections for each supported RDBMS under "Data Models and the Object System". Perhaps a better numbering of the chapters would be in place. For example making the Postgres part section 4.2.1 and the Oracle part section 4.2.2 etc.
I guess it's a matter of preference, but personally I'd prefer to see the latter implemented.
I've changed the variables and parameters to p_* and v_*.
"As far as taking on the object system documentation - YES. I think folks would find this tremendously useful. "
Ok. I'm taking on the object system documentation then. Apart from the need of adding more examples to the documentation, would you guys be so kind and give me a list of the improvements you'd like to see made to this part of the documentation?
Again, can anyone provide me with explanations of the name_method and abstract_p parameters?

4: Response to doc enhanced: Chapter 4: Data Models and the Object System (response to 1)

Posted by russell muetzelfeldt on 04/16/02 09:36 AM

name_method is the name of a plsql function that will return a human-readable name for an object of that type with a specified object_id. It's called by acs_object.name(), so you can for example

select object_id,acs_object.name(object_id) from acs_objects

and get human understandable names without having to know what type of objects you're dealing with or how they're named.

one example of this is /permissions/ which needs to display object names that make at least some sense to people, but has no need to have any in-depth understanding of the objects it's assigning permissions to.

as for abstract_p, I was under the impression that it was a wart left over from the original design of the acs4 object model, and isn't actually used for anything. ISTR that it was meant to flag object types that would never be instantiated, just derived from. (but take that with a grain of salt - I haven't looked at that in a while)

5: Response to doc enhanced: Chapter 4: Data Models and the Object System (response to 1)

Posted by Don Baccus on 04/16/02 04:25 PM

I wouldn't assume most folks are using PG. Well, in numbers that's probably true but in terms of paying clients more probably still use Oracle. We should run a poll someday ...

And if someone were to step up to the plate and offer to start a porting effort to DB2 or some other capable RDBMS, we'd be open to it. If two RDBMS examples side-by-side are a mess, think of what three or more would be like!

So ... yes, I prefer your latter option just as you do.

As far as exactly what's wanted by folks ... e-mail Roberto Mello and Vinod Kurup (who is out of the country for a few more days, I think) and see if you can get some info from them.