Return-Path:
A user mapping connector allows a user name to be transformed in a manner that depends on the functionality of the connector. In some cases, no connection to + an external repository is required (for example, simple string transformations), while in some cases one might imagine such a connector consulting with (say) an + LDAP system to look up a specific name.
+ +A user name is just a string, which is designed to represent a user identity. Some user names have specific forms - for instance, Active Directory user names are
+ often represented in the form user@domain
. But, most importantly, the exact name used can often depend on the particular system being addressed.
As is the case with all connectors under the ManifoldCF umbrella, a user mapping connector consists of a single part:
+ +The mapping connector abstraction makes use of, or introduces, the following concepts:
+ +Concept | What it is |
---|---|
Configuration parameters | A hierarchical structure, internally represented as an XML document, which describes a specific configuration of a specific mapping connector, i.e. how the connector should do its job; see org.apache.manifoldcf.core.interfaces.ConfigParams |
Mapping connection | An mapping connector instance that has been furnished with configuration data |
User name | The name of a user, which is often a Kerberos principal name, e.g. john@apache.org |
Connection management/threading/pooling model | How an individual mapping connector class instance is managed and used |
A very good place to start is to read the javadoc for the mapping connector interface. You will note that the javadoc describes the usage and pooling model for a + connector class pretty thoroughly. It is very important to understand the model thoroughly in order to write reliable connectors! Use of static variables, for one thing, + must be done in a very careful way, to avoid issues that would be hard to detect with a cursory test.
+ +The second thing to do is to examine some of the provided mapping connector implementations. The only connector presently included (the Regular Expression + user mapping connector) demonstrates some of the sorts of techniques you will need for an effective + implementation. You will also note that all of these connectors extend a framework-provided mapping connector base class, found at + org.apache.manifoldcf.authorities.mappers.BaseMappingConnector. This base class furnishes some basic bookkeeping logic for managing the + connector pool, as well as default implementations of some of the less typical functionality a connector may have. For example, connectors are allowed to have + database tables of their own, which are instantiated when the connector is registered, and are torn down when the connector is removed. This is, however, not + very typical, and the base implementation reflects that.
+ +The principle methods an implementer should be concerned with for creating a mapping connector are the following:
+ +Method | What it should do |
---|---|
mapUser() | Given an input user name, find the corresponding output user name |
outputConfigurationHeader() | Output the head-section part of a mapping connection ConfigParams editing page |
outputConfigurationBody() | Output the body-section part of a mapping connection ConfigParams editing page |
processConfigurationPost() | Receive and process form data from a mapping connection ConfigParams editing page |
viewConfiguration() | Output the viewing HTML for a mapping connection ConfigParams object |
These methods come in two broad classes: (a) functional methods for doing the work of the connector; (b) UI methods for configuring a connection. Together they + do the heavy lifting of your connector.
+ + +The crawler UI uses a tabbed layout structure, and thus each of these elements must properly implement the tabbed model. This means that the "header" methods + above must add the desired tab names to a specified array, and the "body" methods must provide appropriate HTML which handles both the case where a tab is + displayed, and where it is not displayed. Also, it makes sense to use the appropriate css definitions, so that the connector UI pages have a similar look-and-feel + to the rest of ManifoldCF's crawler ui. We strongly suggest starting with one of the supplied mapping connector's UI code, both for a description of the arguments + to each page, and for some decent ideas of ways to organize your connector's UI code.
+ +ManifoldCF's framework provides a number of helpful services designed to make the creation of a connector easier. These services are summarized below. + (This is not an exhaustive list, by any means.)
+ +For UI method support, these too are very useful:
+ +It's always a good idea to make use of an existing infrastructure component, if it's meant for that purpose, rather than inventing your own. There are, however, + some limitations we recommend you adhere to.
+ +If you are tempted to violate these rules, it may well mean you don't understand something important. At the very least, we'd like to know why. Send email + to dev@manifoldcf.apache.org with a description of your problem and how you are tempted to solve it.
+A user mapping connector allows a user name to be transformed in a manner that depends on the functionality of the connector. In some cases, no connection to + an external repository is required (for example, simple string transformations), while in some cases one might imagine such a connector consulting with (say) an + LDAP system to look up a specific name.
+ +A user name is just a string, which is designed to represent a user identity. Some user names have specific forms - for instance, Active Directory user names are
+ often represented in the form user@domain
. But, most importantly, the exact name used can often depend on the particular system being addressed.
As is the case with all connectors under the ManifoldCF umbrella, a user mapping connector consists of a single part:
+ +The mapping connector abstraction makes use of, or introduces, the following concepts:
+ +Concept | What it is |
---|---|
Configuration parameters | A hierarchical structure, internally represented as an XML document, which describes a specific configuration of a specific mapping connector, i.e. how the connector should do its job; see org.apache.manifoldcf.core.interfaces.ConfigParams |
Mapping connection | An mapping connector instance that has been furnished with configuration data |
User name | The name of a user, which is often a Kerberos principal name, e.g. john@apache.org |
Connection management/threading/pooling model | How an individual mapping connector class instance is managed and used |
A very good place to start is to read the javadoc for the mapping connector interface. You will note that the javadoc describes the usage and pooling model for a + connector class pretty thoroughly. It is very important to understand the model thoroughly in order to write reliable connectors! Use of static variables, for one thing, + must be done in a very careful way, to avoid issues that would be hard to detect with a cursory test.
+ +The second thing to do is to examine some of the provided mapping connector implementations. The only connector presently included (the Regular Expression + user mapping connector) demonstrates some of the sorts of techniques you will need for an effective + implementation. You will also note that all of these connectors extend a framework-provided mapping connector base class, found at + org.apache.manifoldcf.authorities.mappers.BaseMappingConnector. This base class furnishes some basic bookkeeping logic for managing the + connector pool, as well as default implementations of some of the less typical functionality a connector may have. For example, connectors are allowed to have + database tables of their own, which are instantiated when the connector is registered, and are torn down when the connector is removed. This is, however, not + very typical, and the base implementation reflects that.
+ +The principle methods an implementer should be concerned with for creating a mapping connector are the following:
+ +Method | What it should do |
---|---|
mapUser() | Given an input user name, find the corresponding output user name |
outputConfigurationHeader() | Output the head-section part of a mapping connection ConfigParams editing page |
outputConfigurationBody() | Output the body-section part of a mapping connection ConfigParams editing page |
processConfigurationPost() | Receive and process form data from a mapping connection ConfigParams editing page |
viewConfiguration() | Output the viewing HTML for a mapping connection ConfigParams object |
These methods come in two broad classes: (a) functional methods for doing the work of the connector; (b) UI methods for configuring a connection. Together they + do the heavy lifting of your connector.
+ + +The crawler UI uses a tabbed layout structure, and thus each of these elements must properly implement the tabbed model. This means that the "header" methods + above must add the desired tab names to a specified array, and the "body" methods must provide appropriate HTML which handles both the case where a tab is + displayed, and where it is not displayed. Also, it makes sense to use the appropriate css definitions, so that the connector UI pages have a similar look-and-feel + to the rest of ManifoldCF's crawler ui. We strongly suggest starting with one of the supplied mapping connector's UI code, both for a description of the arguments + to each page, and for some decent ideas of ways to organize your connector's UI code.
+ +ManifoldCF's framework provides a number of helpful services designed to make the creation of a connector easier. These services are summarized below. + (This is not an exhaustive list, by any means.)
+ +For UI method support, these too are very useful:
+ +It's always a good idea to make use of an existing infrastructure component, if it's meant for that purpose, rather than inventing your own. There are, however, + some limitations we recommend you adhere to.
+ +If you are tempted to violate these rules, it may well mean you don't understand something important. At the very least, we'd like to know why. Send email + to dev@manifoldcf.apache.org with a description of your problem and how you are tempted to solve it.
+