Keel 2.1RC2

org.keel.services.persist
Interface PersistentMetaData

All Known Implementing Classes:
AbstractPersistentMetaData

public interface PersistentMetaData

This object contains the "definition" of a Persistent, all of the Meta-data that associates it with a particular database table. Each persistent has a name, which is assigned arbitrarily (but uniquely) within it's "schema". This name is used to refer to the Persistent within Model objects. Each field in the persistent likewise has a name, which may or may not be the same as the field name in the actual database. This allows the field names to be altered for compatibility with a particular database by changing only the configuration file, not the application. The same is true of table names.

Version:
$Revision: 1.9 $ $Date: 2004/05/03 19:31:22 $
Author:
Michael Nash

Field Summary
static java.lang.String ROLE
           
 
Method Summary
 boolean allowsNull(java.lang.String fieldName)
          Determine if the specified field may contain null.
 boolean collectStatistics()
          Return true if we are collecting Bean statistics for this Persistent.
 void configurePersistent(Configuration newConfig)
          This is configuration for the underlying Persistent
 java.lang.Object getAttribute(java.lang.String fieldName, java.lang.String attribName)
          Get a named "attribute" of this field from the setup meta-data for the Persistent.
 java.util.Map getAttributes(java.lang.String fieldName)
          Return any special additional attributes configured for the specified field.
 AuthorizationManager getAuthManager()
          If securable, then each peristent can have it's own authorization manager
 int getCacheSize()
          Get the size of the cache (in elements) used for this Persistent.
 java.lang.String getCharset()
          Return the current object's character set
 java.lang.String getClassName()
          A particular persistent may be implemented by a specified class, in which case an instance of this class is created when a "create" on this persistent is called
 java.lang.String getDatabaseName(java.lang.String fieldName)
          Get the name of the field in the actual database, that is, the name to be used in constructing SQL statement to refer to this field.
 DatabaseType getDatabaseType()
          Return the name of the DatabaseType implementation configured for this Persistent.
 DataSourceComponent getDataSource()
          Return the DataSourceComponent used for this Persistent.
 java.lang.String getDBFieldName(java.lang.String fieldName)
          Get the name of this field as it is stored in the database (the column name), actually used in SQL.
 java.lang.String getDBType(java.lang.String fieldName)
          Retrieve the database storage type of the specified field.
 java.lang.String getDefaultValue(java.lang.String fieldName)
          Get the (read-only) configured default value for the named field, if one was specified.
 java.lang.String getDescription()
          Return a description of this Persistent.
 java.lang.String getDescription(java.lang.String fieldName)
          Return the description of a field
 java.util.Set getDetailNames()
          Return a set of relation names, where each relation is a "detail" relationship between this persistent and another.
 PersistentFactory getFactory()
          Return the current PersistentFactory
 java.util.Set getFieldNames()
          Get a set of all of the fields in this object.
 java.lang.String getFilterMethod(java.lang.String fieldName)
          Return the name of the Filter implementation to be applied to the specified field, if any.
 java.lang.String getHelperClassName()
          Get the name of the class defined as a "Helper" for this Persistent, if any.
 IdGenerator getIdGenerator(java.lang.String fieldName)
          Return the IdGenerator instance configured for a particular field, if any.
 java.util.Set getIndexedFields(java.lang.String indexName)
          Return the set of field names indexed by the named index.
 java.util.Set getIndicies()
          Return an Set of the names of each of the indicies defined on this table on this table
 java.util.Set getKeyFieldNames()
          Get a list of all of the names of the key fields in this object
 int getLength(java.lang.String fieldName)
          Return the maximum length of the specified field, if any maximum is configured.
 java.util.Map getListValidValues(java.lang.String fieldName)
          Returns a map of Valid values (id/description pairs).
 java.lang.String getLookupField(java.lang.String fieldName)
          Added by Santanu Dutt Get a field to use in lookup object
 java.lang.String getLookupFieldDisplay(java.lang.String fieldName)
          Added by Santanu Dutt Get a display field to use in lookup object
 java.lang.String getLookupObject(java.lang.String fieldName)
          Get a field's lookup object - this is the name of another Persistent that can be used to look up valid values for this object.
 java.lang.String getName()
          Get the name of this object
 int getPageSize()
          If the Persistent has been defined as having a specific "page size" (for display in listings), return the specified size.
 org.apache.oro.text.regex.Pattern getPattern(java.lang.String fieldName)
          Return the valid expression pattern (pre-compiled) for the named field, if any.
 int getPrecision(java.lang.String fieldName)
          Return the precision of the specified field, if any precision is configured.
 Relation getRelation(java.lang.String relationName)
          Get a specific Relation object which describes a relationship involving this persistent
 java.util.Set getRelationNames()
          Get the set of all Relation names associated with this persistent.
 java.lang.String getSchemaName()
          Return the Schema name for this Persistent.
 java.util.Map getStaticValidValues(java.lang.String fieldName)
          Return a map of declared valid values configured for the named field.
 java.lang.String getTableName()
          The name of the actual table (if a relational database) that stores this Persistent.
 java.lang.String getType(java.lang.String fieldName)
          Return the name of the Java type of a field - this is the "internal" type of this field, not the type for the database
 boolean hasField(java.lang.String fieldName)
          This method will return a boolean true if the field is defined in the Persistent false otherwise.
 boolean hasListValidValues(java.lang.String fieldName)
          Checks to make sure that the fieldName is valid, and then checks to make sure that a listValidValues name has been specified for this object (it is not null).
 boolean isAuthManagerBypassAllowed()
          Some securable persistents that are also used by the DBAuthorizationManager to check authoriztion, need to be able to bypass auth.
 boolean isAutoIncremented(java.lang.String fieldName)
          Determine if a specified field is automatically incremented in value as records are added.
 boolean isEncrypted(java.lang.String fieldName)
          Determine if the specified field is stored in an encrypted format.
 boolean isHidden(java.lang.String fieldName)
          Is a given field 'hidden' - these fields are not shown when a list is produced by the generic crud model.
 boolean isKeyField(java.lang.String fieldName)
          Determine if the specified field participates in the primary key for this Persistent.
 boolean isMultiValued(java.lang.String fieldName)
          Method called to determine if a particular field is multi-valued, that is does it have a set of specific values and descriptions
 boolean isReadOnly(java.lang.String fieldName)
          Is a given field readOnly - these fields are not offered for entry when a form is produced by the crud model.
 boolean isRowSecurable()
           
 boolean isSecurable()
          Determine if the Persistent objects specified by this Meta-data are Securable.
 void setDatabaseType(DatabaseType newType)
          Specify the DatabaseType implementation used for this Persistent.
 void setDataSource(DataSourceComponent newSource)
          The Persistent factory (only) hands this PersistentMetaData it's data source component, which it passes on as needed to the Persistent objects themselves.
 void setFactory(PersistentFactory myFactory)
          Specify the PersistentFactory used to create instances of this Persistent.
 void setSchemaName(java.lang.String newName)
          Specify the schema name for this Persistent.
 

Field Detail

ROLE

public static final java.lang.String ROLE
See Also:
Constant Field Values
Method Detail

getDefaultValue

public java.lang.String getDefaultValue(java.lang.String fieldName)
                                 throws PersistenceException
Get the (read-only) configured default value for the named field, if one was specified.

Parameters:
fieldName - Name of the field to retrieve the default for.
Returns:
String The default value for this field.
Throws:
PersistenceException - If there is no such field.

getDetailNames

public java.util.Set getDetailNames()
Return a set of relation names, where each relation is a "detail" relationship between this persistent and another.


getRelation

public Relation getRelation(java.lang.String relationName)
Get a specific Relation object which describes a relationship involving this persistent


getRelationNames

public java.util.Set getRelationNames()
Get the set of all Relation names associated with this persistent.


allowsNull

public boolean allowsNull(java.lang.String fieldName)
                   throws PersistenceException
Determine if the specified field may contain null.

Returns:
True if the field may be null, false if it may not
Throws:
PersistenceException - If there is no such field in this persistent

getAttribute

public java.lang.Object getAttribute(java.lang.String fieldName,
                                     java.lang.String attribName)
                              throws PersistenceException
Get a named "attribute" of this field from the setup meta-data for the Persistent. Each field may have a (read-only) set of attributes defined for it as part of the configuration for this Persistent object. Each attribute has a name and a value. This method allows retrieveal of the values.

Parameters:
fieldName - Name of the field to retrieve the attribute value for.
attribName - Name of the attribute to retrieve.
Returns:
Object The value of the Attribute - often a String, but not necessarily.
Throws:
PersistenceException - If there is no such field, or no such attribute.

getCharset

public java.lang.String getCharset()
Return the current object's character set

Returns:
A string representing this Persistent's character set.

getDescription

public java.lang.String getDescription()
Return a description of this Persistent.

Returns:
A string describing this Persistent

getDescription

public java.lang.String getDescription(java.lang.String fieldName)
                                throws PersistenceException
Return the description of a field

Parameters:
fieldName - The name of the field
Returns:
String The description of the field
Throws:
PersistenceException - If there is no such field

getFieldNames

public java.util.Set getFieldNames()
Get a set of all of the fields in this object.

Returns:
A Set of all of the field names in this object
Throws:
PersistenceException - If the list cannot be retrieved

getDatabaseName

public java.lang.String getDatabaseName(java.lang.String fieldName)
                                 throws PersistenceException
Get the name of the field in the actual database, that is, the name to be used in constructing SQL statement to refer to this field. This may or may not be the same as the internal name of the field

Parameters:
fieldName - The "internal" name for this field
Returns:
The actual name of the field as a column in the underlying database.
Throws:
PersistenceException

getKeyFieldNames

public java.util.Set getKeyFieldNames()
Get a list of all of the names of the key fields in this object

Returns:
An Set of all of the names of the key fields

isKeyField

public boolean isKeyField(java.lang.String fieldName)
Determine if the specified field participates in the primary key for this Persistent.

Parameters:
fieldName - The name of the field
Returns:
boolean True if the field is one of the primary key fields, false if it is not.

getLength

public int getLength(java.lang.String fieldName)
              throws PersistenceException
Return the maximum length of the specified field, if any maximum is configured. Return 0 if no maximum is configured.

Throws:
PersistenceException - If no such field exists

getPrecision

public int getPrecision(java.lang.String fieldName)
                 throws PersistenceException
Return the precision of the specified field, if any precision is configured. Return 0 if none is specified

Parameters:
fieldName - The field requested
Returns:
The precision of the specified field
Throws:
PersistenceException - If the field does not exist in this Persistent

getLookupObject

public java.lang.String getLookupObject(java.lang.String fieldName)
                                 throws PersistenceException
Get a field's lookup object - this is the name of another Persistent that can be used to look up valid values for this object. TODO: Allow this to be a query, not a persistent

Parameters:
fieldName - The name of the field
Returns:
The name of the lookup object, if any
Throws:
PersistenceException - If the specified field does not exist.

getLookupField

public java.lang.String getLookupField(java.lang.String fieldName)
                                throws PersistenceException
Added by Santanu Dutt Get a field to use in lookup object

Parameters:
fieldName - The field name
Returns:
The name of the lookup field
Throws:
PersistenceException - If the specified field does not exist.

getLookupFieldDisplay

public java.lang.String getLookupFieldDisplay(java.lang.String fieldName)
                                       throws PersistenceException
Added by Santanu Dutt Get a display field to use in lookup object

Parameters:
fieldName -
Throws:
PersistenceException - If the specified field does not exist.

getName

public java.lang.String getName()
Get the name of this object

Returns:
String The Persistent object name. Often (but NOT always) the same as the table name in the database

getTableName

public java.lang.String getTableName()
The name of the actual table (if a relational database) that stores this Persistent.


getType

public java.lang.String getType(java.lang.String fieldName)
                         throws PersistenceException
Return the name of the Java type of a field - this is the "internal" type of this field, not the type for the database

Parameters:
fieldName - The name of the field
Returns:
String: The type of the field
Throws:
PersistenceException - If there is no such field in this object

getDBType

public java.lang.String getDBType(java.lang.String fieldName)
                           throws PersistenceException
Retrieve the database storage type of the specified field.

Parameters:
fieldName - Field name
Returns:
String The database-specific type name
Throws:
PersistenceException - If there is no such field

getIndicies

public java.util.Set getIndicies()
Return an Set of the names of each of the indicies defined on this table on this table


getIndexedFields

public java.util.Set getIndexedFields(java.lang.String indexName)
                               throws PersistenceException
Return the set of field names indexed by the named index.

Throws:
PersistenceException - If there is no index with the given name

hasField

public boolean hasField(java.lang.String fieldName)
This method will return a boolean true if the field is defined in the Persistent false otherwise.

Parameters:
fieldName - Name of the field to be tested for
Returns:
boolean

isMultiValued

public boolean isMultiValued(java.lang.String fieldName)
                      throws PersistenceException
Method called to determine if a particular field is multi-valued, that is does it have a set of specific values and descriptions

Parameters:
fieldName - Name of the field
Returns:
boolean True if the field is multi-valued, false if not
Throws:
PersistenceException - If there is no such field

isReadOnly

public boolean isReadOnly(java.lang.String fieldName)
                   throws PersistenceException
Is a given field readOnly - these fields are not offered for entry when a form is produced by the crud model.

Parameters:
fieldName -
Returns:
True of the field is "read only", false if it is not
Throws:
PersistenceException - Ff there is no such field

isHidden

public boolean isHidden(java.lang.String fieldName)
                 throws PersistenceException
Is a given field 'hidden' - these fields are not shown when a list is produced by the generic crud model. This means that only users with update permission to the record can see the value of the specified field.

Parameters:
fieldName - The name of the field to check
Returns:
True if the field is 'hidden', false if it is not
Throws:
PersistenceException - If there is no such field.

getSchemaName

public java.lang.String getSchemaName()
Return the Schema name for this Persistent. This is the part of the name before the period in the full name.


setSchemaName

public void setSchemaName(java.lang.String newName)
                   throws PersistenceException
Specify the schema name for this Persistent.

Throws:
PersistenceException

configurePersistent

public void configurePersistent(Configuration newConfig)
                         throws PersistenceException
This is configuration for the underlying Persistent

Throws:
PersistenceException

setDatabaseType

public void setDatabaseType(DatabaseType newType)
Specify the DatabaseType implementation used for this Persistent.

Parameters:
newType - The DatabaseType implementation used for this Persistent.

getIdGenerator

public IdGenerator getIdGenerator(java.lang.String fieldName)
                           throws PersistenceException
Return the IdGenerator instance configured for a particular field, if any.

Parameters:
fieldName - The field name.
Returns:
IdGenerator The IdGenerator class used to create new sequential id's for this field, if any. Null if this field is not auto-incremented.
Throws:
PersistenceException - If there is no such field name.

getDatabaseType

public DatabaseType getDatabaseType()
Return the name of the DatabaseType implementation configured for this Persistent.

Returns:
DatabaseType A name of a DatabaseType implementation.

collectStatistics

public boolean collectStatistics()
Return true if we are collecting Bean statistics for this Persistent.

Returns:
boolean True if statistics are being collected, false if not.

getCacheSize

public int getCacheSize()
Get the size of the cache (in elements) used for this Persistent. Zero indicates no caching is performed.

Returns:
int Size of the cache in number of elements.

getHelperClassName

public java.lang.String getHelperClassName()
Get the name of the class defined as a "Helper" for this Persistent, if any.

Returns:
String The full classname of the Helper class. Null if no helper is specified.

isAutoIncremented

public boolean isAutoIncremented(java.lang.String fieldName)
                          throws PersistenceException
Determine if a specified field is automatically incremented in value as records are added.

Parameters:
fieldName - The name of the field.
Returns:
boolean True if a form of auto-incrementing is used on this field, False if it is not auto-incremented.
Throws:
PersistenceException - If there is no such field.

getDBFieldName

public java.lang.String getDBFieldName(java.lang.String fieldName)
                                throws PersistenceException
Get the name of this field as it is stored in the database (the column name), actually used in SQL.

Throws:
PersistenceException - If there is no such field

getPattern

public org.apache.oro.text.regex.Pattern getPattern(java.lang.String fieldName)
                                             throws PersistenceException
Return the valid expression pattern (pre-compiled) for the named field, if any.

Throws:
PersistenceException - If there is no such field

hasListValidValues

public boolean hasListValidValues(java.lang.String fieldName)
                           throws PersistenceException
Checks to make sure that the fieldName is valid, and then checks to make sure that a listValidValues name has been specified for this object (it is not null).

Parameters:
fieldName -
Returns:
boolean
Throws:
PersistenceException - If there is no such field

getListValidValues

public java.util.Map getListValidValues(java.lang.String fieldName)
                                 throws PersistenceException
Returns a map of Valid values (id/description pairs). This method returns values if the field found by the given field name has been defined as having list-valid-values, as in this example: List Valid Values are read from two core Keel tables, KeelListHeader and KeelListFooter.

Parameters:
fieldName -
Returns:
Map
Throws:
PersistenceException

getFilterMethod

public java.lang.String getFilterMethod(java.lang.String fieldName)
                                 throws PersistenceException
Return the name of the Filter implementation to be applied to the specified field, if any.

Parameters:
fieldName - The field name
Returns:
String The name of the Filter implementation defined for this field, if any - Null if no filtering required.
Throws:
PersistenceException - If there is no such field.

isEncrypted

public boolean isEncrypted(java.lang.String fieldName)
                    throws PersistenceException
Determine if the specified field is stored in an encrypted format.

Parameters:
fieldName - Field name to check
Returns:
boolean True if the field is specified as encrypted, false otherwise
Throws:
PersistenceException - If there is no such field.

setDataSource

public void setDataSource(DataSourceComponent newSource)
                   throws PersistenceException
The Persistent factory (only) hands this PersistentMetaData it's data source component, which it passes on as needed to the Persistent objects themselves. Only visible within the package.

Throws:
PersistenceException

getDataSource

public DataSourceComponent getDataSource()
Return the DataSourceComponent used for this Persistent. Only visible within the package.

Returns:
DataSourceComponent The DataSourceComponent used for this Persistent.

getPageSize

public int getPageSize()
If the Persistent has been defined as having a specific "page size" (for display in listings), return the specified size.

Returns:
int The page size configured for this Persistent.

getAttributes

public java.util.Map getAttributes(java.lang.String fieldName)
                            throws PersistenceException
Return any special additional attributes configured for the specified field.

Parameters:
fieldName - The name of the field to retrieve the Attribute map for.
Returns:
A Map of attribute names and values for this field.
Throws:
PersistenceException

getStaticValidValues

public java.util.Map getStaticValidValues(java.lang.String fieldName)
                                   throws PersistenceException
Return a map of declared valid values configured for the named field. A field may have a "static" set of valid values, specified in configuration, or it may dynamically figure them out. Applications should call getValidValues from the Persistent object, not this method.

Throws:
PersistenceException

getClassName

public java.lang.String getClassName()
A particular persistent may be implemented by a specified class, in which case an instance of this class is created when a "create" on this persistent is called


setFactory

public void setFactory(PersistentFactory myFactory)
Specify the PersistentFactory used to create instances of this Persistent.

Parameters:
myFactory - The PersistentFactory used to create these Persistent objects.

getFactory

public PersistentFactory getFactory()
Return the current PersistentFactory

Returns:
PersistentFactory

isSecurable

public boolean isSecurable()
Determine if the Persistent objects specified by this Meta-data are Securable. This is required because the individual Persistent objects are not components themselves. Added by Santanu Dutt for Securable Persistent objects


isRowSecurable

public boolean isRowSecurable()

getAuthManager

public AuthorizationManager getAuthManager()
If securable, then each peristent can have it's own authorization manager

Returns:

isAuthManagerBypassAllowed

public boolean isAuthManagerBypassAllowed()
Some securable persistents that are also used by the DBAuthorizationManager to check authoriztion, need to be able to bypass auth. to avoid looping of the auth. function. The bypassing is done by using the setBypassAuthorizationManager(am) in the Persistent interface, But only certain persistents, by using the am-bypass-allowed attr. in configuration, are allowed to have auth. bypassed.


Keel 2.1RC2

Please see keelframework.org for information about new Keel releases.