com.jcorporate.expresso.core.dbobj
Class Schema

java.lang.Object
  com.jcorporate.expresso.kernel.ComponentBase
      com.jcorporate.expresso.kernel.ContainerComponentBase
          com.jcorporate.expresso.core.dbobj.Schema

All Implemented Interfaces:

ComponentLifecycle, Containable, Describable, ExpressoComponent, com.jcorporate.expresso.services.controller.RegistrationFactory, Serializable

Direct Known Subclasses:

ExpressoSchema

public abstract class Schema

extends ContainerComponentBase

implements ComponentLifecycle, com.jcorporate.expresso.services.controller.RegistrationFactory

A Schema contains a collection of DBObjects, Controllers, Jobs, and MessageBundles allowing them to be created all at once, dropped at once, and reported on as a group A schema also contains (optional) a list of ReportPage objects that make up the standard reports for a package

You create your own schema as the hub of your Expresso-based component. To do this, derive your own class from Schema, override the abstract members to give your component a name, component code, etc. And then in the constructor of the schema, you add the various components such as DBOBjects to your schema.

Author:

Michael Nash

See Also:

Serialized Form

Constructor Summary

Schema()
Constructor

Method Summary

void	add(Job oneJob) Deprecated. See the addJob(Class) method instead since Expresso 5.6
void	add(String schemaClass, String setupCode, String descrip, String defaultValue) Deprecated. since 3/04; use addSetup() instead
protected void	addController(Class c) New method of adding a controller to the default category.
protected void	addController(Class c, String categoryName) New method of adding a controller to the default category.
protected void	addController(String controllerName) Add a controller to the default category
protected void	addController(String controllerName, String categoryName) New method to add controller objects to the list of controllers in this Schema object.
protected void	addDBObject(Class c) New method of adding a dbobject to the default category.
protected void	addDBObject(Class c, String categoryName) New method of adding a dbobject to the specified category.
protected void	addDBObject(String dbobjectClass) Method to add a dbobject to the list of dbobjects in this schema
protected void	addDBObject(String dbobjectClass, String otherDBName) Method to add a dbobject to the list of dbobjects in this schema for a named dbother location in the default category.
protected void	addDBObject(String dbobjectClass, String otherDBName, String categoryName) Method to add a dbobject to the list of dbobjects in this schema for a named dbother location and named category.
protected void	addJob(Class c) method of adding a job to the specified category.
void	addReportPage(Class reportClass) Add a new report page to the schema.
void	addReportPage(String reportClassName) Add a new ReportPage to the default category
protected void	addServlet(Class c) New method of adding a servlet to the specified category.
void	addSetup(String setupCode, String descrip, String defaultValue) Add a new setup value to this schema for THIS schema; will not change value if one already exists in Setup table
void	addSetup(String schemaClass, String setupCode, String descrip, String defaultValue) Add a new setup value to the named schema; will not change value if one already exists in Setup table
void	configure(Configuration newConfig) Provide Configurations
boolean	contains(DBObject dbObject) Checks if a particular dbobject resides in a given schema.
void	destroy() Called upon destruction of the service.
Vector	getConfig() Return the list of configuration values required by this schema
List	getControllerList() Return a list of the Controller objects that are members of this schema.
String	getDataContext() Return the name of the context/database connection that this schema is being applied to.
String	getDBName() Deprecated. Use getDataContext() instead. Since v.5.5
Hashtable	getDBObjMap() Retrieves the DBObject Map for table creation.
String	getDefaultComponentCode() Returns the default component code for this schema.
String	getDefaultDescription() Returns the default description for this schema.
static Schema	getInstance()
Enumeration	getJobs() Return an enumeration of the jobs that are members of this schema
Controller	getLoginController() Retrieve the login controller for your schema.
Enumeration	getMembers() Return an enumeration of the database objects that belong to this schema
String	getMessageBundlePath() Return the path, relative to the classpath, of the MessageBundle file for this schema.
URL	getMetadataLocation() Base metadata location.
Controller	getRegistrationController() Retrieve the registration controller.
Vector	getReports() Return the list of ExpressoReport objects that are required by this schema.
int	getRequestingUser() Retrieve the UID of requesting user.
Enumeration	getServlets() Return an enumeration of the servlets that are members of this schema
protected String	getSetupDefault(String paramName, String defaultValue) Return the value if this property is defined in the properties file for this config key.
String	getSetupValue(String key) Retrieve one of the Setup values for the schema.
Controller	getStartController() Return a single transaction as the "starting point" for this application.
protected String	getString(String stringCode) Get the i18N'ized string for this schema
Enumeration	getTests() Deprecated. Since Expresso 5.6 Tests have been separated from the main code base.
String	getVersion() Method to return the current version number of an application Schema.
void	initialize() Initialize Lifecycle event.
static Schema	instantiate(String className) Convenience method to create a Schema object from it's name
void	otherSetup(InstallLog installLog, String dataContext) preferable way of performaing other setup.
void	otherSetup(String dbName) Deprecated. 5.5+; 10/04. use otherSetup(log, dbcontext) instead
void	populateSchemaData(String dbName) Allow populations of sample data where all tables must be set up first.
void	reconfigure(Configuration newConfig) Reconfigure Lifecycle Event.
protected void	requiresVersion(String versionString, String schemaClassName) Method for a schema to define a dependance on another schema with a particular version - e.g. if eContent requires expresso 3.11, it can call this method to ensure that's the version it's being run with
void	setDataContext(String newOther) Set the database name/context for this schema.
void	setDBName(String newOther) Deprecated. Since Expresso 5.6 Use setDataContext(String) instead.
void	setRequestingUser(int uid) Set the user ID of requester.
void	setSetupValue(String key, String value) Sets the setup values for the given key
void	setupDefaultValues(String dbName) Go through each DBobject in the schema and call populateDefaultValues.
void	setupDefaultValuesWithException(String dbName) Go through each DBobject and each Controller in the schema and call default-populate methods.

Methods inherited from class com.jcorporate.expresso.kernel.ContainerComponentBase

getContainerImplementation, locateComponent, setContainerImplementation

Methods inherited from class com.jcorporate.expresso.kernel.ComponentBase

getMetaData, getParent, setMetaData, setParent

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.jcorporate.expresso.kernel.ExpressoComponent

getMetaData, getParent, setParent

Constructor Detail

Schema

public Schema()

Constructor

Method Detail

addDBObject

protected void addDBObject(String dbobjectClass)

Method to add a dbobject to the list of dbobjects in this schema

Parameters:

dbobjectClass - the class name of the DBObject that you want to add.

addDBObject

protected void addDBObject(Class c,
                           String categoryName)

New method of adding a dbobject to the specified category. Call by writing:

Parameters:

c - the class name of the DBObject that you want to add.

categoryName - the category to which this controller belongs.

addDBObject

protected void addDBObject(Class c)

New method of adding a dbobject to the default category. Call by writing: addController("your.class.here.class");

Parameters:

c - the class of the controller that you want to add. If you mis-type your controller name, the compiler will catch it at compile time.

addDBObject

protected void addDBObject(String dbobjectClass,
                           String otherDBName)

Method to add a dbobject to the list of dbobjects in this schema for a named dbother location in the default category. Please note that otherdb tables are not created on a DBCreate run.

Parameters:

dbobjectClass - the name of the database object class to use

otherDBName - The dbcontext to use for this dataobject.

addDBObject

protected void addDBObject(String dbobjectClass,
                           String otherDBName,
                           String categoryName)

Method to add a dbobject to the list of dbobjects in this schema for a named dbother location and named category.

Parameters:

dbobjectClass - The name of the dbobject to add to the schema.

otherDBName - The dbcontext to use for this dataobject.

categoryName - the navigation category to use for this database object

addController

protected void addController(String controllerName)

Add a controller to the default category

Parameters:

controllerName - the String name of the controller to add to the schema

addController

protected void addController(Class c)

New method of adding a controller to the default category. Call by writing: addController("your.class.here.class");

Parameters:

c - the class of the controller that you want to add. If you mis-type your controller name, the compiler will catch it at compile time.

addController

protected void addController(String controllerName,
                             String categoryName)

New method to add controller objects to the list of controllers in this Schema object. We no longer add the object itself (as this is not very efficient, to say the least) we only store the *name* of the controller.

Parameters:

controllerName - The class name of the controller object

categoryName - The category to which this controller belongs

addController

protected void addController(Class c,
                             String categoryName)

New method of adding a controller to the default category. Call by writing: addController("your.class.here.class");

Parameters:

c - the class of the controller that you want to add. If you mis-type your controller name, the compiler will catch it at compile time.

categoryName - the category to which this controller belongs.

addReportPage

public void addReportPage(Class reportClass)

Add a new report page to the schema.

Parameters:

reportClass - the class of the report. Usually obtained by typing out the class name and adding ".class" at the end. Example: com.jcorporate.ext.report.DownloadUsers.class

addReportPage

public void addReportPage(String reportClassName)

Add a new ReportPage to the default category

Parameters:

reportClassName - The class name of a "ReportPage" object that is part of this schema

add

public void add(Job oneJob)
         throws DBException

Deprecated. See the addJob(Class) method instead since Expresso 5.6

Add a new Job object to this schema

Parameters:

oneJob - New job object to add as a member to this schema

Throws:

DBException - If the object cannot be added

addJob

protected void addJob(Class c)

method of adding a job to the specified category. Call by writing: addController("your.class.here.class");

Parameters:

c - the class of the controller that you want to add. If you mis-type your controller name, the compiler will catch it at compile time.

addServlet

protected void addServlet(Class c)

New method of adding a servlet to the specified category. Call by writing: addController("your.class.here.class");

Parameters:

c - the class of the controller that you want to add. If you mis-type your controller name, the compiler will catch it at compile time.

add

public void add(String schemaClass,
                String setupCode,
                String descrip,
                String defaultValue)
         throws DBException

Deprecated. since 3/04; use addSetup() instead

Add a new setup value to this schema

Parameters:

schemaClass - Class name of this schema

setupCode - Code of the new setup value

descrip - A description of the new setup value

defaultValue - A default value for the new setup value

Throws:

DBException - If the value cannot be added to the setup table

See Also:

addSetup(java.lang.String, java.lang.String, java.lang.String, java.lang.String)

addSetup

public void addSetup(String schemaClass,
                     String setupCode,
                     String descrip,
                     String defaultValue)
              throws DBException

Add a new setup value to the named schema; will not change value if one already exists in Setup table

Parameters:

schemaClass - Class name of this schema

setupCode - Code of the new setup value

descrip - A description of the new setup value

defaultValue - A default value for the new setup value

Throws:

DBException - If the value cannot be added to the setup table

addSetup

public void addSetup(String setupCode,
                     String descrip,
                     String defaultValue)
              throws DBException

Add a new setup value to this schema for THIS schema; will not change value if one already exists in Setup table

Parameters:

setupCode - Code of the new setup value

descrip - A description of the new setup value

defaultValue - A default value for the new setup value

Throws:

DBException - If the value cannot be added to the setup table

getConfig

public Vector getConfig()

Return the list of configuration values required by this schema

Returns:

Vector A vector of setup/configuration values for this schema

getControllerList

public List getControllerList()

Return a list of the Controller objects that are members of this schema. Controllers are instantiated if not already cached. However, since ControllerFactory caches the instances, performance of calls after the initial call is faster

Returns:

java.util.List of Controller objects that belong to this schema

getDefaultComponentCode

public String getDefaultComponentCode()

Returns the default component code for this schema. Useful for automated component testing/installation

Returns:

the component code string as defined by the derived schema class

getDefaultDescription

public String getDefaultDescription()

Returns the default description for this schema. Useful for automated component testing/installation

Returns:

the component friendly name as defined by the derived schema class

getDBName

public String getDBName()

Deprecated. Use getDataContext() instead. Since v.5.5

Return the name of the context/database connection that this schema is being applied to. If none is set, then we are applying to the "default" database/context.

Returns:

the database context that this Schema object is associated with.

getDataContext

public String getDataContext()

Return the name of the context/database connection that this schema is being applied to. If none is set, then we are applying to the "default" database/context.

Returns:

the database context that this Schema object is associated with.

Since:

Expresso 5.6

getInstance

public static Schema getInstance()

Returns:

an an instance of this schema instance.

getJobs

public Enumeration getJobs()

Return an enumeration of the jobs that are members of this schema

Returns:

Enumeration List of Transaction objects that belong to this schema

getMembers

public Enumeration getMembers()

Return an enumeration of the database objects that belong to this schema

Returns:

Enumeration List of DBObject objects that belong to this schema

getMessageBundlePath

public String getMessageBundlePath()

Return the path, relative to the classpath, of the MessageBundle file for this schema. For example, the Expresso schema (com.jcorporate.expresso.core.ExpressoSchema) returns "com/jcorporate/expresso/core", as this is where it's message files are stored.

Returns:

A String describing the location of the MessageBundle Path

getReports

public Vector getReports()

Return the list of ExpressoReport objects that are required by this schema.

Returns:

Vector A list of ExpressoReport objects that are standard reports in this schema.

getServlets

public Enumeration getServlets()

Return an enumeration of the servlets that are members of this schema

Returns:

Enumeration List of StdServlet objects that belong to this schema

getSetupDefault

protected String getSetupDefault(String paramName,
                                 String defaultValue)

Return the value if this property is defined in the properties file for this config key.

Parameters:

paramName - Property Name

defaultValue - value if property is not defined

Returns:

String Value of this property in the property file for this DB config.

getStartController

public Controller getStartController()

Return a single transaction as the "starting point" for this application. Each Schema object may define such a transaction, and the appropriate application can then be invoked from that point

Returns:

a Controller Instance of the starting controller point.

getSetupValue

public String getSetupValue(String key)

Retrieve one of the Setup values for the schema.

Parameters:

key - The setup value key

Returns:

java.lang.String the value of the setup value. May be null;

setSetupValue

public void setSetupValue(String key,
                          String value)

Sets the setup values for the given key

Parameters:

key - The name of the setup value.

value - the Value of the setup value.

otherSetup

public void otherSetup(InstallLog installLog,
                       String dataContext)
                throws DBException

preferable way of performaing other setup. Utilizes the context independant logging system.

Parameters:

installLog - the InstallLog implementation that the setup process will log progress to.

dataContext - he database context to execute this process against.

Throws:

DBException - If there's a database communication error

otherSetup

public void otherSetup(String dbName)
                throws DBException

Deprecated. 5.5+; 10/04. use otherSetup(log, dbcontext) instead

Perform any additional setup/intialize functions required by this schema. This is where applications can set up default values for lookup tables, reference values, etc. Subclass does not extend this method if it is not needed.

Parameters:

dbName - The database context to execute this process against.

Throws:

DBException - If there's a database communication error

setDBName

public void setDBName(String newOther)
               throws DBException

Deprecated. Since Expresso 5.6 Use setDataContext(String) instead.

Set the database name/context for this schema. If setDBName is not called, the "default" db name and context is used.

Parameters:

newOther - The name of the context or database to use

Throws:

DBException - If there's a problem switching to the database context.

setDataContext

public void setDataContext(String newOther)
                    throws DBException

Set the database name/context for this schema. If setDBName is not called, the "default" db name and context is used.

Parameters:

newOther - The name of the context or database to use

Throws:

DBException - If there's a problem switching to the database context.

setupDefaultValues

public void setupDefaultValues(String dbName)

Go through each DBobject in the schema and call populateDefaultValues.

See: @see com.jcorporate.expresso.core.dbobj.DBObject.populateDefaultValues

Parameters:

dbName - The name of the database to set this up on.

setupDefaultValuesWithException

public void setupDefaultValuesWithException(String dbName)
                                     throws DBException

Go through each DBobject and each Controller in the schema and call default-populate methods.

See: @see com.jcorporate.expresso.core.dbobj.DBObject.populateDefaultValues See: @see com.jcorporate.expresso.core.controller.Controller.setupDefaultValues

Parameters:

dbName - The name of the database to set this up on.

Throws:

DBException - if a database exception occurs

populateSchemaData

public void populateSchemaData(String dbName)
                        throws DBException

Allow populations of sample data where all tables must be set up first.

Parameters:

dbName - The name to add the data to see com.jcorporate.eforum.ForumSchema#populateSchemaData for example.

Throws:

DBException - if an error occurs while populating the table.

getTests

public Enumeration getTests()

Deprecated. Since Expresso 5.6 Tests have been separated from the main code base.

Return the list of Junit tests in this application

Returns:

An Enumeration of all tests for this schema

getDBObjMap

public Hashtable getDBObjMap()

Retrieves the DBObject Map for table creation.

Returns:

java.util.Hashtable

getString

protected String getString(String stringCode)

Get the i18N'ized string for this schema

Parameters:

stringCode - The string code to find in the messages bundle.

Returns:

The Mapped String

getVersion

public String getVersion()

Method to return the current version number of an application Schema. Individual Schema objects may override this method if they define a version, then other dependant applications can use that information to make sure that the current version dependancies are met.

How to define your own version string:

The format is: MajorVersion.MinorVersion.Release-EA Release Number

MajorVerseion,MinorVersion, and Release represent the typical: 1.0.1 type of version formatting. -EAReleaseNumber is also a number but is optional if you do not wish to use a EA number if the version number.

Examples

• 1.0.1 : First Major Version with a bugfix release.
• 2.2.2-2: Second Major Version, Second Minor Version, Second Bugfix release and it is currently considered ea-2

Returns:

the Version you define for your system.

requiresVersion

protected void requiresVersion(String versionString,
                               String schemaClassName)
                        throws DBException

Method for a schema to define a dependance on another schema with a particular version - e.g. if eContent requires expresso 3.11, it can call this method to ensure that's the version it's being run with

Parameters:

versionString - String the string version this requires.

schemaClassName - the class name to check against.

Throws:

DBException - if an error occurs locating the appropriate schema class

instantiate

public static Schema instantiate(String className)
                          throws DBException

Convenience method to create a Schema object from it's name

Parameters:

className - The ClassName to instantiate

Returns:

A newly initialized Schema Object

Throws:

DBException - if there's an instantiation problem

getMetadataLocation

public URL getMetadataLocation()

Base metadata location. All schemas have the same component metadata, unless you want to specify your own. In which case, you'll want to override based upon your own information.

Specified by:

getMetadataLocation in interface Describable

Overrides:

getMetadataLocation in class ComponentBase

Returns:

java.net.URL

initialize

public void initialize()

Initialize Lifecycle event. Provide quick initialization

Specified by:

initialize in interface ComponentLifecycle

configure

public void configure(Configuration newConfig)
               throws ConfigurationException

Provide Configurations

Specified by:

configure in interface ComponentLifecycle

Parameters:

newConfig - the new configuration object

Throws:

ConfigurationException - if for some reason the Component cannot cope with the configuration sent to it. If this exception is thrown then ZERO reconfiguration takes place. Configure() must be an all or nothing 'transaction'

reconfigure

public void reconfigure(Configuration newConfig)
                 throws ConfigurationException

Reconfigure Lifecycle Event. Nullify values and restart.

Specified by:

reconfigure in interface ComponentLifecycle

Parameters:

newConfig - The new Configuration

Throws:

ConfigurationException - if for some reason the Component cannot cope with the configuration sent to it. If this exception is thrown then ZERO reconfiguration takes place. Configure() must be an all or nothing 'transaction'

destroy

public void destroy()

Description copied from interface: ComponentLifecycle

Called upon destruction of the service. This may or may not have anything to do with container shutdown or reloading.

Specified by:

destroy in interface ComponentLifecycle

getLoginController

public Controller getLoginController()
                              throws ControllerException

Retrieve the login controller for your schema. The default implementation checks the ClassHandler section and returns it or the default (SimpleLogin) if there is none defined in the ClassHandlers. Override for your own apps to have custom and multiple logins and registration controllers.

Specified by:

getLoginController in interface com.jcorporate.expresso.services.controller.RegistrationFactory

Returns:

Controller Instance

Throws:

ControllerException - if there is an error instantiating the controller

getRegistrationController

public Controller getRegistrationController()
                                     throws ControllerException

Retrieve the registration controller. The default version checks the classhandlers section in the expresso-config.xml file and returns what's appropriate there or SimpleRegistration if none is defined.

Specified by:

getRegistrationController in interface com.jcorporate.expresso.services.controller.RegistrationFactory

Returns:

a controller instance for Registration

Throws:

ControllerException - if there is an error instantiating the controller

setRequestingUser

public void setRequestingUser(int uid)

Set the user ID of requester.

Parameters:

uid - ID of requesting user

getRequestingUser

public int getRequestingUser()

Retrieve the UID of requesting user.

Returns:

UID of requesting user, if known. otherwise, returns 0

contains

public boolean contains(DBObject dbObject)

Checks if a particular dbobject resides in a given schema.

Parameters:

dbObject - the object to check against.

Returns:

true if this schema contains this object