content/release/release-2.25/ja_JP/writing-authority-connectors.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> <meta content="Apache Forrest" name="Generator"> <meta name="Forrest-version" content="0.9"> <meta name="Forrest-skin-name" content="lucene"> <title>Writing authority connectors</title> <link type="text/css" href="../skin/basic.css" rel="stylesheet"> <link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet"> <link media="print" type="text/css" href="../skin/print.css" rel="stylesheet"> <link type="text/css" href="../skin/profile.css" rel="stylesheet"> <script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script> <link rel="shortcut icon" href="../images/favicon.ico"> </head> <body onload="init()"> <script type="text/javascript">ndeSetTextSize();</script> <div id="top">  <div class="breadtrail"> <a href="http://www.apache.org/">Apache</a> > <a href="http://manifoldcf.apache.org">ManifoldCF</a> > <a href="">Release Documentation</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script> </div>  <div class="header">  <div class="grouplogo"> <a href="https://www.apache.org"><img class="logoImage" alt="Apache" src="../images/SupportApache-small-128.png" title="Apache Software Foundation"></a> </div>   <div class="projectlogo"> <a href="http://manifoldcf.apache.org"><img class="logoImage" alt="Apache ManifoldCF" src="../images/ManifoldCF-logo.PNG" title="ManifoldCF"></a> </div>  <div class="projectlogo"> <a href="https://www.apache.org/events/current-event.html"><img class="logoImage" src="https://www.apache.org/events/current-event-234x60.png"></a> </div>  <ul id="tabs"> <li> <a class="unselected" href="..">Hello!</a> </li> <li> <a class="unselected" href="../en_US/index.html">English</a> </li> <li> <a class="unselected" href="../ja_JP/index.html">日本語</a> </li> <li> <a class="unselected" href="../zh_CN/index.html">中文</a> </li> </ul>  </div> </div> <div id="main"> <div id="publishedStrip">  <div id="level2tabs"></div>  <script type="text/javascript"></script> </div>  <div class="breadtrail">   </div>   <div id="menu"> <div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">English</div> <div id="menu_1.1" class="menuitemgroup"> <div class="menuitem"> <a href="../en_US/index.html">Welcome</a> </div> <div onclick="SwitchMenu('menu_1.1.2', '../skin/')" id="menu_1.1.2Title" class="menutitle">Documentation</div> <div id="menu_1.1.2" class="menuitemgroup"> <div class="menuitem"> <a href="../en_US/concepts.html">Concepts</a> </div> <div class="menuitem"> <a href="../en_US/included-connectors.html">Compatibility Matrix</a> </div> <div class="menuitem"> <a href="../en_US/faq.html">Frequently Asked Questions</a> </div> <div class="menuitem"> <a href="../en_US/programmatic-operation.html">API Documentation</a> </div> <div class="menuitem"> <a href="../en_US/javadoc.html">Javadoc</a> </div> <div class="menuitem"> <a href="../en_US/how-to-build-and-deploy.html">Building and Deploying</a> </div> <div class="menuitem"> <a href="../en_US/technical-resources.html">Technical Resources</a> </div> <div class="menuitem"> <a href="../en_US/performance-tuning.html">Performance tuning</a> </div> <div class="menuitem"> <a href="../en_US/script.html">Scripting Language</a> </div> <div class="menuitem"> <a href="../en_US/end-user-documentation.html">End-user Documentation (HTML)</a> </div> <div class="menuitem"> <a href="../en_US/end-user-documentation.pdf">End-user Documentation (PDF)</a> </div> </div> </div> <div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">日本語</div> <div id="menu_1.2" class="menuitemgroup"> <div class="menuitem"> <a href="../ja_JP/index.html">概要</a> </div> <div onclick="SwitchMenu('menu_1.2.2', '../skin/')" id="menu_1.2.2Title" class="menutitle">ドキュメント</div> <div id="menu_1.2.2" class="menuitemgroup"> <div class="menuitem"> <a href="../ja_JP/concepts.html">概要</a> </div> <div class="menuitem"> <a href="../ja_JP/included-connectors.html">コネクタ一覧</a> </div> <div class="menuitem"> <a href="../ja_JP/faq.html">Ｑ＆Ａ</a> </div> <div class="menuitem"> <a href="../ja_JP/javadoc.html">Javadoc</a> </div> <div class="menuitem"> <a href="../ja_JP/technical-resources.html">開発者リソース</a> </div> <div class="menuitem"> <a href="../ja_JP/end-user-documentation.html">エンドユーザマニュアル (HTML)</a> </div> <div class="menuitem"> <a href="../ja_JP/end-user-documentation.pdf">エンドユーザマニュアル (PDF)</a> </div> </div> </div> <div onclick="SwitchMenu('menu_1.3', '../skin/')" id="menu_1.3Title" class="menutitle">中文</div> <div id="menu_1.3" class="menuitemgroup"> <div class="menuitem"> <a href="../zh_CN/index.html">概要</a> </div> <div onclick="SwitchMenu('menu_1.3.2', '../skin/')" id="menu_1.3.2Title" class="menutitle">文档</div> <div id="menu_1.3.2" class="menuitemgroup"> <div class="menuitem"> <a href="../zh_CN/concepts.html">概要</a> </div> <div class="menuitem"> <a href="../zh_CN/included-connectors.html">连接器一览</a> </div> <div class="menuitem"> <a href="../zh_CN/faq.html">Q&A</a> </div> <div class="menuitem"> <a href="../zh_CN/javadoc.html">Javadoc</a> </div> <div class="menuitem"> <a href="../zh_CN/technical-resources.html">开发人员资源</a> </div> <div class="menuitem"> <a href="../zh_CN/end-user-documentation.html">用户手册(HTML)</a> </div> </div> </div> <div id="credit"></div> <div id="roundbottom"> <img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>  <div id="credit2"></div> </div>   <div id="content"> <h1>Writing authority connectors</h1> <div id="minitoc-area"> <ul class="minitoc"> <li> <a href="#Writing+an+Authority+Connector">Writing an Authority Connector</a> <ul class="minitoc"> <li> <a href="#Key+concepts">Key concepts</a> </li> <li> <a href="#Implementing+the+Authority+Connector+class">Implementing the Authority Connector class</a> <ul class="minitoc"> <li> <a href="#Principle+methods">Principle methods</a> </li> <li> <a href="#Notes+on+connector+UI+methods">Notes on connector UI methods</a> </li> </ul> </li> <li> <a href="#Implementation+support+provided+by+the+framework">Implementation support provided by the framework</a> </li> <li> <a href="#DO%27s+and+DON%27T+DO%27s">DO's and DON'T DO's</a> </li> </ul> </li> </ul> </div> <a name="N1000E"></a><a name="Writing+an+Authority+Connector"></a> <h2 class="h3">Writing an Authority Connector</h2> <div class="section"> <p></p> <p>An authority connector to a repository allows a repository's security model to be enforced by a search engine. Its only function is to convert a user name (which is often a Kerberos principal name) into a set of _access tokens_.</p> <p></p> <p>The definition of an access token within ManifoldCF for a given repository is completely defined by the connectors that deal with that repository, with one exception. That exception is for Active Directory. Active Directory is so prevalent as a repository authorization mechanism that ManifoldCF currently treats it as the "default" authority - that is, if you don't specify another authority when you define a repository connection, ManifoldCF presumes that you mean that Active Directory should be the controlling authority for the connection. In that case, an access token is simply an Active Directory SID.</p> <p></p> <p>For those repositories that do not use Active Directory as their authorization mechanism, an authority connector should be written, along with the repository connector for the repository. Access tokens in that case represent a contract between your implementation of the authority connector for the repository, and the repository connector for the repository. They must work together to define access tokens that will limit document access when used properly within any search engine query.</p> <p></p> <p>As is the case with all connectors under the ManifoldCF umbrella, an authority connector consists of a single parts:</p> <p></p> <ul> <li>A class implementing an interface (in this case, <em>org.apache.manifoldcf.authorities.interfaces.IAuthorityConnector</em>)</li> </ul> <p></p> <a name="N10035"></a><a name="Key+concepts"></a> <h3 class="h4">Key concepts</h3> <p></p> <p>The authority connector abstraction makes use of, or introduces, the following concepts:</p> <p></p> <table class="ForrestTable" cellspacing="1" cellpadding="4"> <tr> <th colspan="1" rowspan="1">Concept</th><th colspan="1" rowspan="1">What it is</th> </tr> <tr> <td colspan="1" rowspan="1">Configuration parameters</td><td colspan="1" rowspan="1">A hierarchical structure, internally represented as an XML document, which describes a specific configuration of a specific authority connector, i.e. <strong>how</strong> the connector should do its job; see <em>org.apache.manifoldcf.core.interfaces.ConfigParams</em></td> </tr> <tr> <td colspan="1" rowspan="1">Authority connection</td><td colspan="1" rowspan="1">An authority connector instance that has been furnished with configuration data</td> </tr> <tr> <td colspan="1" rowspan="1">User name</td><td colspan="1" rowspan="1">The name of a user, which is often a Kerberos principal name, e.g. <em>john@apache.org</em></td> </tr> <tr> <td colspan="1" rowspan="1">Access token</td><td colspan="1" rowspan="1">An arbitrary string, which is only meaningful within the context of a specific authority connector, that describes a quantum of authorization</td> </tr> <tr> <td colspan="1" rowspan="1">Connection management/threading/pooling model</td><td colspan="1" rowspan="1">How an individual authority connector class instance is managed and used</td> </tr> <tr> <td colspan="1" rowspan="1">Service interruption</td><td colspan="1" rowspan="1">A specific kind of exception that signals ManifoldCF that the output repository is unavailable, and gives a best estimate of when it might become available again; see <em>org.apache.manifoldcf.agents.interfaces.ServiceInterruption</em></td> </tr> </table> <p></p> <a name="N10097"></a><a name="Implementing+the+Authority+Connector+class"></a> <h3 class="h4">Implementing the Authority Connector class</h3> <p></p> <p>A very good place to start is to read the javadoc for the authority 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.</p> <p></p> <p>The second thing to do is to examine some of the provided authority connector implementations. The Documentum connector, the LiveLink connector, the Memex connector, and the Meridio connector all include authority connectors which demonstrate (to some degree) the sorts of techniques you will need for an effective implementation. You will also note that all of these connectors extend a framework-provided authority connector base class, found at <em>org.apache.manifoldcf.authorities.authorities.BaseAuthorityConnector</em>. 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.</p> <p></p> <a name="N100AC"></a><a name="Principle+methods"></a> <h4>Principle methods</h4> <p></p> <p>The principle methods an implementer should be concerned with for creating an authority connector are the following:</p> <p></p> <table class="ForrestTable" cellspacing="1" cellpadding="4"> <tr> <th colspan="1" rowspan="1">Method</th><th colspan="1" rowspan="1">What it should do</th> </tr> <tr> <td colspan="1" rowspan="1"><strong>getAuthorizationResponse()</strong></td><td colspan="1" rowspan="1">Obtain the authorization response, given a user name</td> </tr> <tr> <td colspan="1" rowspan="1"><strong>outputConfigurationHeader()</strong></td><td colspan="1" rowspan="1">Output the head-section part of an authority connection <em>ConfigParams</em> editing page</td> </tr> <tr> <td colspan="1" rowspan="1"><strong>outputConfigurationBody()</strong></td><td colspan="1" rowspan="1">Output the body-section part of an authority connection <em>ConfigParams</em> editing page</td> </tr> <tr> <td colspan="1" rowspan="1"><strong>processConfigurationPost()</strong></td><td colspan="1" rowspan="1">Receive and process form data from an authority connection <em>ConfigParams</em> editing page</td> </tr> <tr> <td colspan="1" rowspan="1"><strong>viewConfiguration()</strong></td><td colspan="1" rowspan="1">Output the viewing HTML for an authority connection <em>ConfigParams</em> object</td> </tr> </table> <p></p> <p>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.</p> <p></p> <p>The <em>getAuthorizationResponse()</em> method returns an <em>AuthorizationResponse</em> object, which can describe a number of conditions:</p> <p></p> <table class="ForrestTable" cellspacing="1" cellpadding="4"> <tr> <th colspan="1" rowspan="1">Condition</th><th colspan="1" rowspan="1">Meaning</th> </tr> <tr> <td colspan="1" rowspan="1">RESPONSE_OK</td><td colspan="1" rowspan="1">The access tokens for the user were successfully obtained from the repository, and are being returned</td> </tr> <tr> <td colspan="1" rowspan="1">RESPONSE_UNREACHABLE</td><td colspan="1" rowspan="1">The repository is currently unreachable, and appropriate disabling tokens are being returned</td> </tr> <tr> <td colspan="1" rowspan="1">RESPONSE_USERNOTFOUND</td><td colspan="1" rowspan="1">The user was not found within the repository, and appropriate disabling tokens are being returned</td> </tr> <tr> <td colspan="1" rowspan="1">RESPONSE_USERUNAUTHORIZED</td><td colspan="1" rowspan="1">The user was found, but was in some way disabled, and appropriate disabling tokens are being returned</td> </tr> </table> <p></p> <p></p> <p>In all cases, the connector returns access tokens. But in the case where token lookup has failed in some way, it is the responsibility of the connector to insure that inappropriate content is not viewed. Usually, this is done by ingesting a "global deny" token attached to all documents from the given repository, and then having the associated authority connector return this global deny token when error conditions apply.</p> <p></p> <p></p> <a name="N1015C"></a><a name="Notes+on+connector+UI+methods"></a> <h4>Notes on connector UI methods</h4> <p></p> <p>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 authority 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.</p> <p></p> <a name="N1016B"></a><a name="Implementation+support+provided+by+the+framework"></a> <h3 class="h4">Implementation support provided by the framework</h3> <p></p> <p>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.)</p> <p></p> <ul> <li>Lock management and synchronization (see <em>org.apache.manifoldcf.core.interfaces.LockManagerFactory</em>)</li> <li>Cache management (see <em>org.apache.manifoldcf.core.interfaces.CacheManagerFactory</em>)</li> <li>Local keystore management (see <em>org.apache.manifoldcf.core.KeystoreManagerFactory</em>)</li> <li>Database management (see <em>org.apache.manifoldcf.core.DBInterfaceFactory</em>)</li> </ul> <p></p> <p>For UI method support, these too are very useful:</p> <p></p> <ul> <li>Multipart form processing (see <em>org.apache.manifoldcf.ui.multipart.MultipartWrapper</em>)</li> <li>HTML encoding (see <em>org.apache.manifoldcf.ui.util.Encoder</em>)</li> <li>HTML formatting (see <em>org.apache.manifoldcf.ui.util.Formatter</em>)</li> </ul> <p></p> <a name="N101B2"></a><a name="DO%27s+and+DON%27T+DO%27s"></a> <h3 class="h4">DO's and DON'T DO's</h3> <p></p> <p>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.</p> <p></p> <ul> <li>DO make use of infrastructure components described in the section above</li> <li>DON'T make use of infrastructure components that aren't mentioned, without checking first</li> <li>NEVER write connector code that directly uses framework database tables, other than the ones installed and managed by your connector</li> </ul> <p></p> <p>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.</p> </div> </div>  <div class="clearboth"> </div> </div> <div id="footer">  <div class="lastmodified"> <script type="text/javascript"></script> </div> <div class="copyright"> Copyright © 2009-2024 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a> </div> <div class="copyright"> Apache ManifoldCF, ManifoldCF, Apache Forrest, Forrest, Apache Solr, Solr, Apache, the Apache feather logo, the Apache Forrest logo, and the Apache ManifoldCF logo are trademarks of The Apache Software Foundation. Documentum and EMC are a trademarks of EMC Corporation. SharePoint, Windows, and Microsoft are trademarks of Microsoft, Inc. FileNet P8 and IBM are trademarks of IBM, Inc. LiveLink and OpenText are trademarks of OpenText, Inc. QBase, MetaCarta, and GTS are trademarks of QBase, Inc. Meridio and Autonomy are trademarks of Hewlett Packard, Inc. Alfresco is a trademark of Alfresco Software, Inc. Jira is a trademark of Atlassian, Inc. </div>  </div> </body> </html>

content/release/release-2.25/ja_JP/writing-authority-connectors.html (361 lines of code) (raw):