Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [stellation-res] Partial API freeze coming; API audits requested. 
On Sun, 2002-09-15 at 20:14, Dave Shields wrote:
> On Sun, Sep 15, 2002 at 02:06:52PM +0000, Mark C. Chu-Carroll wrote:
> > 
> > We're going to be trying to partially freeze some of the Stellation APIs
> > over the next two weeks. It would be very helpful to us if anyone with
> > I'm in the process of changing it to a set of methods (leaving out
> > exceptions for brevity):
> > 	void createResource(Integer id);
> > 	OutputStream getOutputStream(Integer id);
> > 	void writeProperties(Integer id, PropertyMap properties);
> > 	void setResourceTime(long time);
> > 
> 
> createResource is pretty vague - what kind of resource?

It's deliberately vague. The basic notion is that when we're dealing
with outputting an artifact, there are three distinct things going on:
creation of some kind of external resource that will store the artifact;
writing the basic artifact data out to the external resource; and
writing the artifact metadata. (Conceptually, timestamp is just
another bit of metadata, but since it's used in a special way, we've
been treating it differently. We could get rid of the setResourceTime,
and just let it be a part of a single writeMetadata method.) What
the resource is, depends on both the kind of artifact and the kind
of output.

To give a concrete example: when you're using a FileOutput,  and you
go to process a CompoundArtifact, you need to create a directory. I'd
argue that it makes more sense for a compound artifact to have its
createResource create a directory, and its getOutputStream return null. 
For a ZipOutput, createResource would be creating the ZipEntry, and
getting the outputStream would be using that ZipEntry to get a stream.

Right now, there's one method, and the resource creation (if any), and
the writing of metadata are hidden inside of what looks like a simple
getter method. So you've got major functionality hidden in side effects
of a getter - and that's confusing. (Also, I suspect that when we get a
bit further into fine-grained stuff, there are going to be some
dynamically computer properties that aren't necessarily known at the
time that the artifacts transient data is written out - so separating
the writing of metadata from the writing of transient content is going
to be important.)

	-Mark
 
-- 
Mark Craig Chu-Carroll,  IBM T.J. Watson Research Center  
*** The Stellation project: Advanced SCM for Collaboration
***		http://www.eclipse.org/stellation
*** Work Email: mcc@xxxxxxxxxxxxxx  ------- Personal Email:
markcc@xxxxxxxxxxx

Attachment: signature.asc
Description: This is a digitally signed message part

Back to the top