Emmet has been designed to to be customized without the need to touch the actual Java source files. Customization is performed using the Chico customization mechanisms as described in this page.
At the low level, Emmet uses Spring dependency injection to configure the various servlets in an installation. A site configuration is represented as a number of Spring XML wiring files which specify various configuration parameters and wire up various "beans" to perform tasks such as validation, filtering, persistence and access control.
Building a Emmet configuration from scratch would be a daunting task, so the base distribution comes with a set of Spring wiring files that implement the common cases. These configurations are designed use the Chico infrastructure so that simple tailoring can be implemented by setting property values in a couple of properties files.
The Chico documentation describes:
The XML wiring files for Emmet may be found in the emmet.webapp directory; look in the respective src/main/webapp/WEB-INF directory in the source tree. In addition, there is a demosite directory that contains a template for site-specific customization of a free standing Emmet installation.
While the Chico site customization approach deals with simple cases, a major customization of Emmet is likely to require a degree of understanding of Spring wiring files, and of the way that Spring IoC, Spring MVC, and Spring Security work. If you are not familiar with Spring, we recommend that you read (at least) the IoC and MVC chapters of the online Spring Framework Reference, and the relevant parts of the Spring Security Reference.
These placeholder properties, which provide the values for that are used for placeholders (as described above) have over-arching significance to the Emmet webapp. These properties are defined in the default-emmet-substitution.properties file and should be overridden in your site's substitution.properties file.
| Property Value Default Purpose | hostname DNS name / IP address "localhost" This gives the primary host for site services. It can be overridden on a per-service basis |
| Property Value Default Purpose | db.hostname DNS name / IP address "localhost" This gives the host for site databases. It can be overridden on a per-service basis |
| Property Value Default Purpose | db.username String "root" This gives the username for site databases. It can be overridden on a per-service basis |
| Property Value Default Purpose | db.password String "whatever" This gives the password for site databases. It can be overridden on a per-service basis |
| Property Value Default Purpose | site.title A short site name "Emmet" A common name for the site, used in various JSPs, etcetera. |
| Property Value Default Purpose | emmet.site.title A short site name ${site.title} This site name as used in the Emmet JSPs. |
| Property Value Default Purpose | emmet.hostname DNS name / IP address ${hostname} This gives the host for the Emmet service. |
| Property Value Default Purpose | emmet.db.hostname DNS name / IP address ${db.hostname} This gives the host for Emmet's backend database. This may have no effect, depending on the userDetails and emmet.db.type parameters. |
| Property Value Default Purpose | emmet.db.username String ${db.username} This gives the username to be used for accessing the Emmet backend database. |
| Property Value Default Purpose | emmet.db.password String ${db.password} This gives the password to be used for accessing the Emmet backend database. |
| Property Value Default Purpose | emmet.container relative path "emmet" This gives the common servlet container path for the Emmet services. |
| Property Value Default Purpose | emmet.db.type "mysql" or "derby" "mysql" This selects the SQL database type used by Emmet. MySQL needs to be set up separately, but "derby" selects an embedded Derby server that is run in the Tomcat container. At this time, "derby" is not fully tested. |
| Property Value Default Purpose | emmet.db an SQL logical database name "test" This gives the logical database name that contains Emmet's user details tables. |
| Property Value Default Purpose | emmet.security see below "none" This selects the primary security scheme. |
| Property Value Default Purpose | emmet.userDetails see below "test" This selects the user details store configuration. |
| Property Value Default Purpose | emmet.site see below see below This selects the site's access control configuration. |
| Property Value Default Purpose | emmet.email.host DNS name ${hostname} This gives the local SMTP server for outgoing mail messages |
| Property Value Default Purpose | emmet.email.address RFC 821 email address accountadmin@${emmet.email.host} This gives the address that will be used in the "From" field of outgoing email messages |
The security configs are defined in the *.xml files in the WEB-INF directory, and controlled by the emmet.security, emmet.userDetails and emmet.site placeholder properties. The emmet.security property can have the following values:
Descriptions of the template security schemes are provided below. (Of course you are free to create your own scheme from scratch.)
The emmet.userDetails property can have the following values:
Note that an Emmet user details store is needed for the Emmet user management servlet to function.
The emmet.site property selects the Emmet-siteAuthorization-*.xml file that will be used. This file contains the filter interceptor definitions that determine what authorities are required to access different parts of the webapp's web namespace. If also contains a Map that tells the SpringSecurity filters how to deal with requests that require the user to authorize themselves. (For normal web pages, the user's browser is typically redirecting to a login page, but for a RESTful web API the requestor is typically given a 401 UNAUTHORIZED response with some kind of challenge.)
Emmet defines the default for emmet.site to be "emmet", but this will be replaced with different value by projects that implement Emmet-based authorization and access control by means of a Maven dependency on the emmet.webapp module. For example, the default value for a Danno-based site will be "danno".
The configuration files in the following sections are designed to be overriden in your site overrides.properties file.
The properties described in this section configure the URIs used by Emmet as well as various aspect of the user management servlet. The properties are defined in the Emmet-common.xml file. Use emmetProps as the bean name in the overrides; e.g.
emmetProps.emmet.home.url = \
http://${emmet.hostname}/${emmet.container}/somewhere.html"| Property Value Default Purpose | emmet.home.url URL "http://${emmet.hostname}/${emmet.container}/index.html" This is the "home" URL for Emmet. |
| Property Value Default Purpose | emmet.logout.url URL "http://${emmet.hostname}/${emmet.container}/logout" This is the URL that logs the user out. |
| Property Value Default Purpose | emmet.styles URL "http://${emmet.hostname}/${emmet.container}/stylesheets" This is the URL for the directory containing the stylesheets used by Emmet. |
| Property Value Default Purpose | emmet.styles URL "http://${emmet.hostname}/${emmet.container}/stylesheets" This is the URL for the directory containing the stylesheets used by Emmet. |
| Property Value Default Purpose | emmet.site.title Text "$emmet.site.title" This is the title of the site Emmet is embedded in. |
| Property Value Default Purpose | emmet.container URL "$emmet.container" This is the host-relative URL for Emmet's web container. |
| Property Value Default Purpose | emmet.userUri.base URL "http://$emmet.hostname/users/" This is the base URL for Emmet user identifiers. |
| Property Value Default Purpose | emmet.userName.pattern Regex "[a-zA-Z][a-zA-Z0-9._-]*" This pattern gives the syntax for Emmet usernames. |
| Property Value Default Purpose | emmet.roles.prefix String "ROLE_" This is the prefix for Emmet's authority names; see Emmet-common.xml for caveats. |
| Property Value Default Purpose | emmet.roles.all Comma separated list of Strings "ROLE_USER,ROLE_ADMIN,ROLE_OAI,ROLE_ANNOTATOR" This is the complete set of authorities used by this installation. |
| Property Value Default Purpose | emmet.roles.default Comma separated list of Strings "ROLE_USER" This is the set of authorities assigned by default to a new user. |
| Property Value Default Purpose | emmet.role.admin String "ROLE_ADMIN" This is authority required for Emmet user administration functions. |
| Property Value Default Purpose | emmet.password.defaultExpiry Not implemented yet "90 days" This is default expiry value for passwords. |
| Property Value Default Purpose | emmet.password.maxExpiry Not implemented yet "never" This is maximum allowed expiry value for passwords. |
| Property Value Default Purpose | emmet.account.defaultExpiry Not implemented yet "never" This is default expiry value for accounts. |
| Property Value Default Purpose | emmet.account.maxExpiry Not implemented yet "never" This is maximum allowed expiry value for accounts. |
| Property Value Default Purpose | emmet.reset.timeout.minutes Duration in minutes "30" This is expiry time for a password reset link. |
| Property Value Default Purpose | emmet.activation.timeout.minutes Duration in minutes "1440" This is expiry time for an account activation link. |
The remaining properties are found in the Emmet-db.xml file, and configure the backend SQL database for the Emmet user details service.
| Property Value Default Purpose | jdbc.driver.class string database dependent This property gives the name of the JDBC driver class name that Jena should use to access the backend SQL database. Refer to the Jena documentation for supported drivers. |
| Property Value Default Purpose | jdbc.user string "${emmet.db.username}" This property gives the database user name to be used to access the triplestore. |
| Property Value Default Purpose | jdbc.password string "${emmet.db.password}" This property gives the database user password to be used to access the triplestore. |
| Property Value Default Purpose | jdbc.database.type string database dependent This property tells the Jena code what type of database is being used. Refer to the Jena documentation for valid values. |
| Property Value Default Purpose | jdbc.database.url string database dependent This property gives the JDBC URL for connecting to the database. This URL typically includes the hostname for the database server, the name of a logical database or table space, and additional connection parameters. Refer to the Jena documentation (and database / JDBC driver documentation) for more information on what to use for your chosen database backend. |
This scheme disables all authorization and access control for the site.
This scheme uses authorization based on username / password authentication entered using a login form. Username / password pairs are recorded in the user details store selected by the emmet.userDetails placedholder property. SpringSecurity's remember-me, anonymous and logout functionality is also enabled.
This scheme uses authorization based a combination of OpenID and user / password authentication. For registered users (with OpenID or user/password credentials), the local user details store provides the authorities that are granted on successful login. Non-registered users with valid OpenID credentials are granted (configurable) default authorities. The scheme also allows you to configure the set of OpenID providers deemed to provide acceptable credentials.
This scheme uses an authorization scheme based on Shibboleth authentication. The site is configured as a Shibboleth "Service Provider" (SP) with an associated remote Shibboleth "Identity Provider" (IDP). Local authorization maps the attributes associated with a Shibboleth credential set to a SpringSecurity UserDetails object and associated authorities / roles.
This scheme uses hybrid authorization based on Shibboleth and a local details store. It is analogous to "openid-hybrid".
This scheme is for testing Shibboleth integration, etcetera. (It is currently set up for a three-way hybrid between Shibboleth, OpenId and local authorization.)