[stellation-res] Primitive level API for WVCM

[Mark C Chu-Carroll <markcc@xxxxxxxxxx>]

Here is the primitive level API for
WVCM. I'll also post this on the wiki later tonight.

        -Mark

l/*******************************************************************************
 *
Copyright
(c)
2003,
2004
IBM
Corporation
and
others.
 *
All
rights
reserved.
  This
program
and
the
accompanying
materials
 *
are
made
available
under
the
terms
of
the
Common
Public
License
v1.0
 *
which
accompanies
this
distribution,
and
is
available
at
 *
http://www.eclipse.org/legal/cpl-v10.html
 *

 *
Contributors:
 *
IBM
-
Initial
API
and
implementation
 ******************************************************************************/

package
org.eclipse.stellation.newstore.backend;

import
java.io.InputStream;
import
java.io.OutputStream;
import
java.util.List;
import
java.util.Map;

import
org.eclipse.stellation.newstore.accesscontrol.AccessControlList;
import
org.eclipse.stellation.newstore.accesscontrol.ActivityAccessControlList;
import
org.eclipse.stellation.newstore.accesscontrol.GroupAccessControlList;
import
org.eclipse.stellation.newstore.accesscontrol.RepositoryAccessControlList;
import
org.eclipse.stellation.util.StringList;

/**
 *
The
interface
for
the
primitive
backend
accessor
for
a
Stellation
 *
WVCM
repository.
 *

 *
In
this
implementation,
all
resources
have
three
types
associated
with
them.
 *
<ol>
 *
<li>
A
WVCM
specified
mime
content
type,
which
describes
what
kind
of
content
 *
     the
resource
contains,
and
is
also
used
to
determine
which
content
handler
to
 use
 *
     to
store
and
retrieve
the
resource.
 *
<li>
A
"vtype".
The
vtype
specifies
how
the
resource
fits
into
the
versioning
 *
    model.
There
are
three
vtypes:
Nonversioned,
Base,
and
Version.
 *
<li>
An
"rtype".
The
rtype
is
the
resource
type
in
WVCM.
 *
</ol>
 *
 */
public
interface
IPrimitiveAccessor {
    
    public
static
final
String STELL_NAMESPACE = "http://stellation.eclipse.org/namespace";
    
    public
static
final
String WVCM_NAMESPACE = "";
    
    
    /**
     *
Constant
for
"built-in"
content
type
for
a
resource
with
     *
no
content.
     */
    public
static
final
String CONTENT_NONE = "none";

    /**
     *
Constant
for
content
type
for
text
documents
     */
    public
static
final
String CONTENT_TEXT = "text/plain";

    /**
     *
Constant
for
content
type
for
binary
content
resources
     */
    public
static
final
String CONTENT_BINARY = "application/octetstream";

    /**
     *
The
constant
for
the
vtype
for
base
resources.
     */
    public
static
final
int
VTYPE_BASE = 1;
    
    
    /**
     *
Constant
for
the
vtype
of
version
resources.
Every
resource
with
     *
vtype
version
is
associated
with
one
resource
with
vtype
base.
     */
    public
static
final
int
VTYPE_VERSION = 2;
    
    /**
     *
Constant
for
the
vtype
of
non-versioned
resources.
     */
    public
static
final
int
VTYPE_NONVERSIONED = 3;

    public
static
final
String VTYPE_NAMES[] = new
String[] { "",
"BASE",
"VERSION",
"NONV"
}; 
    
    /**
     *
The
rtype
for
a
basic,
simple
resource.
     */
    public
static
final
int
RTYPE_SIMPLE = 0;

    /**
     *
The
rtype
for
a
folder
resource.
All
folder
resources
have

     *
a
binding
list
associated
with
them.
     */
    public
static
final
int
RTYPE_FOLDER = 1;

    /**
     *
The
rtype
for
a
configuration
resource.
If
the
vtype
is
BASE,
then
     *
the
resource
has
an
ID
for
a
resource
of
rtype
FOLDER
which
is
the
     *
configuration
root.
If
the
vtype
is
VERSION
(meaning,
it's
a
     *
baseline),
then
the
resource
     *
has
a
set
of
version
resources
associated
with
it.
     */
    public
static
final
int
RTYPE_CONFIGURATION = 2;

    /**
     *
The
rtype
for
an
activity
resource.
The
vtype
of
an
activity
is
     *
always
NONVERSIONED.
An
activity
has
a
checkout
list
and
a
version
list
     *
associated
with
it.
     */
    public
static
final
int
RTYPE_ACTIVITY = 3;
    
    public
static
final
String RTYPE_NAMES[] = new
String[] { "SIMPLE",
"FOLDER",
"CONF",
"ACT"
};

    /**
     *
Register
a
component
that
manages
storage
for
some
MIME
type.
     *
@param
a_sm
     */
    public
void
registerContentTypeStorageManager(String a_mimeType,
            IContentTypeStorageManager
a_sm);

    /*
==============================================
     * Resource related
methods
     */
    
    /**
     *
Create
a
new
configuration
base
resource.
     *
@param
a_rootDir
the
root
directory
of
the
configuration
     *
@param
a_properties
a
map
containing
the
properties
to
be
set
for
the
     *
 new
configuration.
     *
@return
the
ID
of
the
configuration
     *
@throws
BackendException
if
the
root
identifier
isn't
a
folder
base
resource.
     */
    public
ITypeLabelledIdentifier createConfiguration(ITypeLabelledIdentifier a_rootDir,
Map a_properties) throws
BackendException;
    
    /**
     *
Get
the
ID
of
the
root
folder
of
a
configuration
     *
@param
a_conf
the
ID
of
the
configuration
     *
@return
the
ID
of
the
root
folder
     *
@throws
BackendException
if
the
configuration
ID
parameter
is
not
found,
or
if
it
is
     *
     not
an
ID
for
a
configuration
object.
     *

     */
    public
ITypeLabelledIdentifier getConfigurationRootID(ITypeLabelledIdentifier
a_conf) throws
BackendException;

    /**
     *
Create
an
activity
resource
in
the
database.
     *
@param
a_name
the
name
for
the
new
activity
resource
     *
@param
a_properties
a
map
of
properties
for
the
activity.
     *
@return
     */
    public
ITypeLabelledIdentifier createActivity(String a_name, String a_desc, 
               
                AccessControlList
a_acl, Map a_properties) throws
BackendException;

    /**
     *
Add
a
resource
with
vtype
VERSION
to
the
resource
list
of
an
activity
     *
@param
a_activity
the
identifier
for
the
activity
     *
@param
a_resource
the
identifier
for
the
resource
     *
@return
     */
    public
void
addResourceToActivity(ITypeLabelledIdentifier a_activity, ITypeLabelledIdentifier
a_resource) throws
BackendException;

    /**
     *
Create
a
baseline
resource.
     *
@param
a_base
the
configuration
resource
that
is
the
base
for
this
baseline.
     *
@param
a_members
a
list
of
version
resources
that
are
members
of
this
baseline.
     *
@param
a_properties
a
map
of
properties
to
be
set
for
the
new
resource.
     *
@return
     */
    public
ITypeLabelledIdentifier createBaseline(ITypeLabelledIdentifier a_base,
List a_members, List a_parents, Map a_properties) throws
BackendException;

    /**
     *
Create
a
base
object
for
a
versioned
file
resource.
     *
@param
a_properties
the
properties
for
the
new
resource.
     *
@return
     */
    public
ITypeLabelledIdentifier createVersionedFile(Map a_properties) throws
BackendException;

    /**
     *
CReate
a
new
version
of
a
versioned
file
resource.
     *
@param
a_base
the
ID
of
the
base
resource.
     *
@param
a_parents
a
list
of
the
immediate
ancestors
of
the
new
version.
     *
@param
a_ctype
the
content
type
for
the
resources
content.
     *
@param
a_content
an
InputStream
from
which
the
content
of
the
resource
will
be
read.
     *
@param
a_properties
the
set
of
property
values
for
the
new
resource.
     *
@return
the
ID
of
the
new
version
resource.
     */
    public
ITypeLabelledIdentifier createFileVersion(ITypeLabelledIdentifier a_base,
List a_parents, String a_ctype,
            InputStream
a_content, Map a_properties) throws
BackendException;

    
    /**
     *
Create
a
versioned
folder
base
resource.
     *
@param
a_properties
the
list
of
properties
for
the
folder
resource.
     *
@return
the
ID
of
the
new
resource
     *
@throws
BackendException
     */
    public
ITypeLabelledIdentifier createVersionedFolder(Map a_properties) throws
BackendException;

    /**
     *
Create
a
new
version
of
a
folder
resource.
     *
@param
a_base
the
ID
of
the
folder
base
resoruce.
     *
@param
a_parents
a
ilst
of
the
IDs
of
the
folder
parent
versions
     *
@param
a_bindings
the
binding
list
for
the
folder
     *
@param
a_properties
the
folder
properties
     *
@return
the
ID
of
the
new
folder
     *
@throws
BackendException
     */
    public
ITypeLabelledIdentifier createFolderVersion(ITypeLabelledIdentifier a_base,
List a_parents,
            BindingList
a_bindings, Map a_properties) throws
BackendException;
    
    /**
     *
Create
a
new
version
of
a
folder
resource
     *
@param
a_base
the
base
folder
     *
@param
a_parents
a
list
of
parent
versions
     *
@param
a_bindings
the
binding
list
for
the
new
version
     *
@param
a_ctype
the
content
type
for
the
folder
resource
content
     *
@param
a_content
an
input
stream
to
read
the
content
from
     *
@param
a_properties
the
new
version's
properties
     *
@return
the
ID
of
the
new
version
     *
@throws
BackendException
     */
    public
ITypeLabelledIdentifier createFolderVersion(ITypeLabelledIdentifier a_base,
List a_parents, BindingList a_bindings,
               
                     
                  String a_ctype,
InputStream a_content, Map a_properties) throws
BackendException;

    /**
     *
Retrieve
the
binding
list
for
a
folder
version.
     *
@param
a_folder
the
ID
of
the
folder
     *
@return
the
binding
list
     *
@throws
BackendException
     */
    public
BindingList getFolderBindings(ITypeLabelledIdentifier a_folder) throws
BackendException;

    /**
     *
Retreieve
the
content
of
a
resource.
     *
@param
a_resource
the
ID
of
the
resource.
     *
@param
a_out
an
output
stream
to
write
the
resource
content
to.
     *
@throws
BackendException
     */
    public
void
getResourceContent(ITypeLabelledIdentifier a_resource, OutputStream a_out)
throws
BackendException;

    /**
     *
Store
the
content
for
a
new
resource
     *
This
should
probably
be
deprecated,
since
the
resource
treation
methods
have
been
modified
to
accept

     *
the
content
at
creation
time.
     *
@param
a_resid
     *
@param
a_ctype
     *
@param
a_content
     *
@throws
BackendException
     */
    public
void
storeResourceContent(ITypeLabelledIdentifier a_resid, String a_ctype, InputStream
a_content) throws
BackendException;

    /**
     *
Get
the
MIME
type
of
the
content
of
a
resource
     *
@param
a_resource
the
ID
of
the
resource
     *
@return
the
MIME
type
     *
@throws
BackendException
     */
    public
String getResourceContentType(ITypeLabelledIdentifier a_resource) throws
BackendException;

    /**
     *
Get
the
values
of
a
specified
list
of
properties
for
a
resource
     *
@param
a_resource
the
ID
of
the
resource
     *
@param
a_propnames
the
names
of
the
properties
     *
@return
a
map
from
name
to
value
for
the
requested
resources.
     *
@throws
BackendException
     */
    public
Map getResourceProperties(ITypeLabelledIdentifier a_resource, List a_propnames)
throws
BackendException;

    /**
     *
Get
a
list
of
the
names
of
all
properties
defined
on
a
resource.
     *
@param
a_resource
the
Resource
ID
     *
@return
a
list
of
property
names
     *
@throws
BackendException
     */
    public
List getResourcePropertyNames(ITypeLabelledIdentifier a_resource) throws
BackendException;

    /**
     *
Get
the
vtype
of
a
resource.
This
will
be
one
of:
 VYPE_BASE,
VTYPE_VERSION,
or
VTYPE_NONVERSIONED
     *
@param
a_resource
the
ID
of
the
resource
     *
@return
the
versioning
type
of
the
resource
     *
@throws
BackendException
     */
    public
int
getResourceVersioningType(ITypeLabelledIdentifier a_resource) throws
BackendException;
    
    /**
     *
Get
the
ID
of
the
base
resource
associated
with
a
particular
version
resource.
     *
@param
a_vid
the
ID
of
the
version
resource
     *
@return
the
ID
of
the
base
resource
     *
@throws
BackendException
     */
    public
ITypeLabelledIdentifier getBaseForVersion(ITypeLabelledIdentifier a_vid)
throws
BackendException;

    /**
     *
Get
the
resource
type
for
the
resource.
This
will
be
one
of:
SIMPLE,
FOLDER,
CONFIGURATION,
ACTIVITY.
     *
@param
a_resource
the
ID
of
the
resource
     *
@return
the
resource
type
     *
@throws
BackendException
     */
    public
int
getResourceType(ITypeLabelledIdentifier a_resource) throws
BackendException;
    
    /**
     *
Set
a
set
of
resource
properties.
(This
method
will
only
work
on
Base
or
Nonversioned
resources;
version
     *
resources
do
not
change
ofter
they
are
created.
     *
@param
a_resource
the
ID
of
the
resource
     *
@param
a_properties
ta
name
to
value
map
of
the
properties
to
store
     *
@throws
BackendException
     */
    public
void
setResourceProperties(ITypeLabelledIdentifier a_resource, Map a_properties)
throws
BackendException;

    /**
     *
Perform
a
checkout
of
a
version
resource
within
a
given
activity.
     *
@param
a_activity
the
ID
of
the
activity
     *
@param
a_resource
the
ID
of
the
resource
     *
@param
forkOK
a
boolean
indicating
whether
the
checkout
should
go
ahead
even
if
the
version
already
has
     *
     a
successor.
     *
@throws
BackendException
     */
    public
void
checkoutResource(ITypeLabelledIdentifier a_activity, ITypeLabelledIdentifier
a_resource, boolean
a_forkOK) throws
BackendException;

    /**
     *
Checkin
a
checked
out
resource.
The
resource
identifier
should
be
the
current
version
of
the
resource
     *
in
the
specified
activity.

     *
@param
a_activity
the
activity
where
the
checkout
occurred.
     *
@param
a_resource
the
ID
of
the
new
version
being
checked
in.
(This
version
must
have
already
been
created
     *
 using
createXVersion.
     *
@throws
BackendException
     */
    public
void
checkinResource(ITypeLabelledIdentifier a_activity, ITypeLabelledIdentifier
a_resource)  throws
BackendException;

    /*
==============================================
     * User related methods
     *
     */
    
    /**
     *
Get
the
username
of
the
user
authenticated
to
use
this
accessor
     */
    public
String getCurrentUser(); 
    
    /**
     *
Create
a
new
userid
in
the
repository
     *
@param
a_username
     *
@param
a_fullname
     *
@param
a_password
     *
@throws
BackendException
     */
    public
void
addUser(String a_username, String a_fullname, String a_password)  throws
BackendException;

    /**
     *
Change
the
password
associated
with
a
user
account
     *
@param
a_username
     *
@param
a_password
     *
@throws
BackendException
     */
    public
void
updateUserPassword(String a_username, String a_password)  throws
BackendException;

    /**
     *
Remove
a
userid's
access
to
the
repository.
(Does
not
actually
delete
the
account,
just
disables
it.
Deleting
it
     *
would
create
validity
issues
in
the
system
history.
     *
@param
a_username
     *
@throws
BackendException
     */
    public
void
removeUser(String a_username) throws
BackendException;

    /*
==============================================
     * Group related
methods
     *
     */
    
    /**
     *
Create
a
new
authorization
group
     *

     */
    public
void
createGroup(String a_groupname, String a_groupdesc) throws
BackendException;

    /**
     *
Add
a
list
of
users
to
an
authorization
group
     *
@param
a_groupname
     *
@param
a_users
     *
@throws
BackendException
     */
    public
void
addUsersToGroup(String a_groupname, StringList a_users) throws
BackendException;

    public
StringList getGroupMembers(String a_groupname) throws
BackendException;

    public
void
removeUsersFromGroup(String a_groupname, StringList a_users) throws
BackendException;

    public
StringList getUserGroups(String a_user) throws
BackendException;
    
    public
GroupAccessControlList getGroupAccessControlList(String a_group) throws
BackendException;
    
    public
ActivityAccessControlList getActivityAccessControlList(ITypeLabelledIdentifier
a_activity) throws
BackendException;
    
    public
RepositoryAccessControlList getRepositoryAccessControlList() throws
BackendException;
    
    public
void
setGroupAccessControlList(String a_group, GroupAccessControlList a_gacl)
throws
BackendException;
    
    public
void
setActivityAccessControlList(ITypeLabelledIdentifier a_activity, ActivityAccessControlList
a_aacl) throws
BackendException;
    
    public
void
setRepositoryAccessControlList(RepositoryAccessControlList a_racl) throws
BackendException;
    


    


}


Mark Craig Chu-Carroll,  IBM T.J.
Watson Research Center  
*** The Stellation project: Advanced SCM Research
***      http://stellation.eclipse.org
*** Work: mcc@xxxxxxxxxxxxxx/Home: markcc@xxxxxxx