com.sssw.rts.adminapi
Interface AgiAdmElement

All Superinterfaces:

AgiAdmChanges, AgiAdmElementBase, AgiAdmPropertyBag

All Known Subinterfaces:

AgiAdmCluster, AgiAdmClusterServer, AgiAdmContainer, AgiAdmDatabase, AgiAdmDesignElement, AgiAdmDirectory, AgiAdmEjbJar, AgiAdmGroup, AgiAdmServer, AgiAdmUser, AgiAdmUserReference, AgiDatabase, AgiServer

public interface AgiAdmElement

extends AgiAdmElementBase, AgiAdmPropertyBag, AgiAdmChanges

Implemented by objects that represent entities that reside on the SilverStream Server. Contains constant values for permissions types (see the setPermissions method) and element property constants that are common for several types of elements, as descibed in the list that follows.

See all the interfaces that subclass this one for their lists of element types.

Field Summary

static String	ACL_KEY Key for storing ACLs in hashtables.
static String	APPLY_TO_DESC Specifies whether the permissions changes are to be applied not only to the element itself but also to all of its descendants.
static String	APPLY_TO_DESC_SUPPORTED Specifies whether the ability to apply permission changes not only to an item but also to its descendants is supported.
static String	DIRECTORY_LIST_SECURITY The element type for the Directory List Security element.
static int	GET_PERMS_AS_ACL Flag for getPermissions.
static int	GET_PERMS_DEFAULT Flag for getPermissions.
static String	PROP_CERTIFICATE Certificate property.
static String	PROP_DESCRIPTION Description property.
static String	PROP_DOMAIN Domain property.
static String	PROP_FULL_NAME Full name property.
static String	PROP_IS_LOCKSMITH Specifies whether a particular Principal (an AgiAdmUser or AgiAdmGroup) has the locksmith privilege.
static String	PROP_LDAP_SERVER LDAP server name property.
static String	PROP_NAME Name property.
static String	PROP_NISPLUS_SERVER NIS+ server name property.
static String	PROP_PARENT_URL Parent URL property.
static String	PROP_PASSWORD Password property.
static String	PROP_QUAL_NAME Fully qualified name property.
static String	PROP_TYPE Type property.
static String	PROP_URL URL property.
static String	REQUIRE_LOGIN Specifies whether to require login at access to the element.
static String	REQUIRE_LOGIN_SUPPORTED Specifies whether the ability to require login at access to the element is supported.

Method Summary

Hashtable	getPermissions(int flags) Retrieve the permissions currently set on the element.
URL	getServerURL() Return the URL of the server where the element resides.
URL	getURL() Return the URL of the element.
Enumeration	getVariables(AgoPermission permType) Return an enumeration of table column names ("variable names") so that the caller could construct expressions for the given permission type.
boolean	isAuthorized(AgoPermission[] permTypes, AgiAdmSession session) Check if the caller has the specified type(s) of access to the element.
void	setPermissions(Hashtable perms) Set element's permissions.

Methods implemented from interface com.sssw.rts.adminapi.AgiAdmElementBase

delete, getName, getType

Methods implemented from interface com.sssw.rts.adminapi.AgiAdmPropertyBag

getProperties, getProperty, setProperties, setProperty

Methods implemented from interface com.sssw.rts.adminapi.AgiAdmChanges

cancelChanges, saveChanges

Field Detail

PROP_NAME

public static final String PROP_NAME

Name property. Common for all elements.

PROP_TYPE

public static final String PROP_TYPE

Type property. Common for all elements.

PROP_URL

public static final String PROP_URL

URL property. Common for all elements.

PROP_DOMAIN

public static final String PROP_DOMAIN

Domain property. Specifies which NT Domain the element belongs. Used for elements of type AgiAdmUser.NTUSER, AgiAdmGroup.NTGROUP, AgiAdmDirectory.NTUSERS, and AgiAdmDirectory.NTGROUPS.

PROP_LDAP_SERVER

public static final String PROP_LDAP_SERVER

LDAP server name property.

PROP_NISPLUS_SERVER

public static final String PROP_NISPLUS_SERVER

NIS+ server name property.

PROP_PARENT_URL

public static final String PROP_PARENT_URL

Parent URL property. Used by element types AgiAdmDirectory.PACKAGE, AgiAdmDesignElement.APP_OBJECT, AgiAdmDirectory.DIRECTORY, and AgiAdmDesignElement.SERVLET.

For a Package or an Application (Business) Object, the parent URL is that of the parent package, if the item resides in a package, or that of AgiAdmDirectory.APP_OBJECTS, if the item resides on the topmost level (which is the level of the Application Objects directory).

For a servlet directory (AgiAdmDirectory.DIRECTORY) the parent URL is that of the parent directory or that of the database where the servlet directory resides, if it is located at the topmost level. For a servlet, the parent URL is that of the parent servlet directory.

PROP_QUAL_NAME

public static final String PROP_QUAL_NAME

Fully qualified name property.

This is not a settable property. Used for elements of types AgiAdmUser and AgiAdmGroup.

PROP_FULL_NAME

public static final String PROP_FULL_NAME

Full name property.

The value of this property can be retrieved for all user types. It can be set for users of type AgiAdmUser.SILVERUSER only.

PROP_DESCRIPTION

public static final String PROP_DESCRIPTION

Description property.

PROP_PASSWORD

public static final String PROP_PASSWORD

Password property. Use for elements of type AgiAdmUser.SILVERUSER.

The value for this property may be set but not retrieved.

PROP_CERTIFICATE

public static final String PROP_CERTIFICATE

Certificate property. Use for elements of type AgiAdmUser.CERTIFICATEUSER. Value type: byte[] (an array of bytes).

The value for this property may be set but not retrieved, and only for users of type AgiAdmUser.CERTIFICATEUSER. Use this property to add client certificate users and to update client certificates.

PROP_IS_LOCKSMITH

public static final String PROP_IS_LOCKSMITH

Specifies whether a particular Principal (an AgiAdmUser or AgiAdmGroup) has the locksmith privilege.

This property is settable and gettable, but it may only be set by a Principal who is a locksmith. Because of the power that this privilege provides, care should be taken with regard to who it's given to and also when it's revoked.

APPLY_TO_DESC_SUPPORTED

public static final String APPLY_TO_DESC_SUPPORTED

Specifies whether the ability to apply permission changes not only to an item but also to its descendants is supported.

APPLY_TO_DESC

public static final String APPLY_TO_DESC

Specifies whether the permissions changes are to be applied not only to the element itself but also to all of its descendants.

The value of this flag does not persist from one permissions change to another; the flag should be used while setting permissions.

REQUIRE_LOGIN_SUPPORTED

public static final String REQUIRE_LOGIN_SUPPORTED

Specifies whether the ability to require login at access to the element is supported.

REQUIRE_LOGIN

public static final String REQUIRE_LOGIN

Specifies whether to require login at access to the element.

This flag persists from one permissions change to the next; its value can be both set and retrieved; it will be ignored in setPermissions if the "require login" feature is not supported by the server for the given type of element.

ACL_KEY

public static final String ACL_KEY

Key for storing ACLs in hashtables.

Use for setting permissions using ACLs and trying to retrieve them as ACLs. Use the key to put your ACL into the hash table on setPermissions and use it on getPermissions if you requested to get permissions as an ACL.

See Also:

AgiAdmElement.getPermissions(int flags), AgiAdmElement.setPermissions(Hashtable perms)

GET_PERMS_DEFAULT

public static final int GET_PERMS_DEFAULT

Flag for getPermissions. Tells the latter to get permissions in a default fashion, that is, as a map of permission types to SilverStream security expressions.

See Also:

AgiAdmElement.getPermissions(int flags)

GET_PERMS_AS_ACL

public static final int GET_PERMS_AS_ACL

Flag for getPermissions. Tells the latter to attempt to get permissions set on an element as an ACL.

If an element's permissions may not be rendered as an ACL, an exception is thrown.

See Also:

AgiAdmElement.getPermissions(int flags)

DIRECTORY_LIST_SECURITY

public static final String DIRECTORY_LIST_SECURITY

The element type for the Directory List Security element.

This element allows the users to manage access lists of who can list directory contents in the server. Use the getPermissions and setPermissions methods on this element to manage these access lists.

Method Detail

getURL

public URL getURL()

Return the URL of the element.

Parameters:

none -

Example:

 Hashtable info = new Hashtable();
 info.put(AgiAdmServer.INFO_DATABASE_NAME, "myDatabase");
 AgiAdmDesignElement table = (AgiAdmDesignElement)server.getElement(
 	"myTable", AgiAdmDesignElement.TABLE, info);
 URL url = table.getURL();
 

getServerURL

public URL getServerURL()

Return the URL of the server where the element resides.

Parameters:

none -

Example:

 Hashtable info = new Hashtable();
 info.put(AgiAdmServer.INFO_DATABASE_NAME, "myDatabase");
 AgiAdmDesignElement table = (AgiAdmDesignElement)server.getElement(
 	"myTable", AgiAdmDesignElement.TABLE, info);
 URL serverURL = table.getServerURL();
 

getPermissions

public Hashtable getPermissions(int flags)
                         throws AgoUnrecoverableSystemException,
                                AgoSecurityException

Retrieve the permissions currently set on the element.

Parameters:

flags - the mode in which the method is to attempt to retrieve the permissions. Possible values: AgiAdmElement.GET_PERMS_DEFAULT and AgiAdmElement.GET_PERMS_AS_ACL.

Usage:

If the default mode is specified, the method returns a hash table where the permissions types are mapped to SilverStream security expressions.

If the ACL mode is specified, the method attempts to return the permissions as an ACL, which will fail if the security permissions were set using complex (advanced) security expressions.

In the ACL mode, the ACL_KEY should be used to get the actual ACL from the returned hash table.

Example:

 Hashtable info = new Hashtable();
 info.put(AgiAdmServer.INFO_DATABASE_NAME, "myDatabase");
 AgiAdmDesignElement table = (AgiAdmDesignElement)server.getElement(
 	"myTable", AgiAdmDesignElement.TABLE, info);
 
 // get permissions set on the table whose name is "myTable"
 // as SilverStream security expressions
 Hashtable perms = form.getPermissions(AgiAdmElement.GET_PERMS_DEFAULT);
 String readPerm = (String)perms.get(AgoPermission.READ);
 String writePerm = (String)perms.get(AgoPermission.WRITE);
 String selectPerm = (String)perms.get(AgoPermission.SELECT);
 String protectPerm = (String)perms.get(AgoPermission.PROTECT);
 String executePerm = (String)perms.get(AgoPermission.EXECUTE);
 
 // attempt to get permissions as an ACL
 Hashtable perms = form.getPermissions(AgiAdmElement.GET_PERMS_AS_ACL);
 AgoAcl acl = (AgoAcl)perms.get(AgiAdmElement.ACL_KEY);
 

See Also:

AgoPermission

setPermissions

public void setPermissions(Hashtable perms)
                    throws AgoUnrecoverableSystemException,
                           AgoSecurityException

Set element's permissions.

Parameters:

perms - the permissions that are to be set on the element

Usage:

perms may contain either a set of permissions types from AgoPermission mapped to security expressions OR the ACL_KEY key mapped to an ACL. Use the createAcl and createAclEntry methods on AgiAdmServer to construct ACLs and ACL entries.

Example:

 // a) set permissions using SilverStream security expressions
 Hashtable info = new Hashtable();
 info.put(AgiAdmServer.INFO_DATABASE_NAME, "myDatabase");
 AgiAdmDirectory formsDir = (AgiAdmDirectory)database.getChild(
 	AgiAdmDirectory.FORMS, AgiAdmDirectory.FORMS, info);
 
 // set the write permission on the Forms directory; apply the change
 // to all the descendants; require login at access
 Hashtable perms = new Hashtable();
 perms.put(AgoPermission.WRITE, "userID() in (userID('administrator'))");
 perms.put(AgiAdmElement.APPLY_TO_DESC, new Boolean(true));
 perms.put(AgiAdmElement.REQUIRE_LOGIN, new Boolean(true));
 formsDir.setPermissions(perms);
 formsDir.saveChanges();
 
 // b) set permissions as an ACL
 
 AgiAdmServer server = AgAdmin.getServer("localhost", -1);
 
 Hashtable perms = new Hashtable();
 
 // Create an ACL
 Acl acl = server.createAcl();
 
 // Get the owner of the ACL
 Principal owner = server.getCurrentPrincipal();
 
 AclEntry world = server.createAclEntry();
 Principal w = server.getWorldPrincipal();
 world.setPrincipal(w);
 world.addPermission(AgoPermission.READ);
 acl.addEntry(owner, world);
 
 // Create an ACL entry
 AclEntry entry = server.createAclEntry();
 
 // Set the principal into the ACL entry
 Principal pr = server.parseUser("nightghost");
 entry.setPrincipal(pr);
 
 // Add the permission for the principal into the ACL entry
 entry.addPermission(AgoPermission.WRITE);
 
 // Add the entry to the ACL
 acl.addEntry(owner, entry);
 
 perms.put(AgiAdmElement.ACL_KEY, acl);
 
 // Now, set the permissions
 server.setPermissions(perms);
 server.saveChanges();
 

See Also:

AgoPermission, AgiAdmServer

isAuthorized

public boolean isAuthorized(AgoPermission[] permTypes,
                            AgiAdmSession session)
                     throws AgoUnrecoverableSystemException,
                            AgoSecurityException

Check if the caller has the specified type(s) of access to the element.

Parameters:

permType - permission type(s) to check

session - session of the caller: ignored if the call is made in client-side code (for example, in a form); pass the session object if it's made in the server-side code (for example, in a page or business object).

Returns:

true if all specified types of access are allowed, false if any one or more access types are disallowed

Usage:

The caller may check for one or several permission types. If at least one of the permission types is not granted, the method will return false for the whole set of permission types supplied in the call.

The method does not check whether or not a specific permission type applies to a specific element type. I.e. the AgoPermission.SELECT permission applies only to AgiAdmDesignElement.TABLE's, yet the caller may check for SELECT on any other type of element that supports the isAuthorized method, and get "true" as the return value from it.

Example:

 // Test all types of access for a server
 AgiAdmServer server = AgAdmin.getServer("myserver", -1);
 AgoPermission[] perms = new AgoPermission[5];
 perms[0] = AgoPermission.READ;
 perms[1] = AgoPermission.WRITE;
 perms[2] = AgoPermission.PROTECT;
 perms[3] = AgoPermission.SELECT;
 perms[4] = AgoPermission.EXECUTE;
 boolean isAuthorized = server.isAuthorized(perms);
 

 // Test execute permission on a page
 Hashtable props = new Hashtable();
 props.put(AgiAdmServer.INFO_DATABASE_NAME, "mydatabase");
 AgiAdmDesignElement myPage = (AgiAdmDesignElement)server.getElement(
		"myPage.html", AgiAdmDesignElement.PAGE, props);
 AgoPermission[] perms = new AgoPermission[1];
 perms[0] = AgoPermission.EXECUTE;
 boolean isAuthorized = myPage.isAuthorized(perms, session);
 

See Also:

AgoPermission

getVariables

public Enumeration getVariables(AgoPermission permType)
                         throws AgoUnrecoverableSystemException,
                                AgoSecurityException

Return an enumeration of table column names ("variable names") so that the caller could construct expressions for the given permission type. Return null if there are no variable names for the specified permissions type.

Parameters:

permType - permissions type

Returns:

java.util.Enumeration - an enumeration of Strings.

Example:

 Hashtable info = new Hashtable();
 info.put(AgiAdmServer.INFO_DATABASE_NAME, "myDatabase");
 AgiAdmDesignElement table = (AgiAdmDesignElement)server.getElement(
 	"myTable", AgiAdmDesignElement.TABLE, info);
 Enumeration e = table.getVariables(AgoPermission.SELECT);
 

See Also:

AgoPermission