cvs: peardoc /en/package/networking/net-ldap2 introduction.xml schemacache.xml

http://cvs.php.net/viewvc.cgi/peardoc/en/package/networking/net-ldap2/introduction.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/package/networking/net-ldap2/introduction.xml
diff -u peardoc/en/package/networking/net-ldap2/introduction.xml:1.1 peardoc/en/package/networking/net-ldap2/introduction.xml:1.2
--- peardoc/en/package/networking/net-ldap2/introduction.xml:1.1	Thu May 28 08:30:07 2009
+++ peardoc/en/package/networking/net-ldap2/introduction.xml	Thu May 28 09:47:18 2009
@@ -103,6 +103,18 @@
                                 and LDIF files. Please note, that Net_LDAP2_LDIF has a little different error handling explained later.
                             </entry>
                         </row>
+                        <row>
+                            <entry><classname>Net_LDAP2_SimpleFileSchemaCache</classname></entry>
+                            <entry>
+                                <classname>Net_LDAP2</classname> features a schema caching facility. This class implements a simple
+                                file based cache that allows Net_LDAP2 to store the schema data that get fetched from LDAP inside a
+                                file to accelerate schema access. Caching the schema can gain some performance, especially with
+                                slow servers or connections. You may use this cache class for example to store the schema object
+                                in a linux tmpfs which will result in caching the schema in the computers memory, enabling nearly
+                                instant access. This cache also features a cache ageing mechanism.
+                                Please see <link linkend="package.networking.net-ldap2.schemacache">Schema caching</link> for more information.
+                            </entry>
+                        </row>
                     </tbody>
                 </tgroup>
             </table>

http://cvs.php.net/viewvc.cgi/peardoc/en/package/networking/net-ldap2/schemacache.xml?view=markup&rev=1.1
Index: peardoc/en/package/networking/net-ldap2/schemacache.xml
+++ peardoc/en/package/networking/net-ldap2/schemacache.xml
<?xml version="1.0" encoding="utf-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.networking.net-ldap2.schemacache">
    <refnamediv>
        <refname>Schema caching</refname>
        <refpurpose>How to enable schema caching</refpurpose>
    </refnamediv>

    <refsection><info><title>Net_LDAP2s schema caching facility</title></info>
	<para>
            <classname>Net_LDAP2</classname> features an easy schema caching facility.
            Caching the schema can gain some performance, especially with slow servers or connections.
            The facility works with an plugin object that must be passed to <classname>Net_LDAP2</classname>s
            <function>registerSchemaCache</function> method. The cache object can be registered (or unregistered)
            at any time, but of course it is the best time right after initializing <classname>Net_LDAP</classname>.
            
            <example><info><title>Enabling/disabling Net_LDAP2s schema caching facility</title></info>
                <programlisting role="php"><![CDATA[
// registering a valid schema cache object is enough to enable the caching facility:
$ldap->registerSchemaCache($myCacheObject);

// unregistering is easy too: just supply null:
$ldap->registerSchemaCache(null);
]]>
                </programlisting>
            </example>
        </para>
        <para>
            The object that gets passed to <function>registerSchemaCache</function> must implement the
            <classname>Net_LDAP2_SchemaCache</classname> interface which demands two methods.
            Initialisation of the cache object is dependent on the class itself. Initialisation should
            be handled inside the cache constructor, however this may vary. Please refer to the cache
            documentation for those details.
            <table><title><classname>Net_LDAP2_SchemaCache</classname> interface methods</title>
                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Method</entry>
                            <entry>Parameter</entry>
                            <entry>Return value</entry>
                            <entry>Description</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>loadSchema</entry>
                            <entry>none</entry>
                            <entry>
                                <classname>Net_LDAP2_Schema</classname>,
                                <classname>Net_LDAP2_Error</classname> or <literal>false</literal></entry>
                            <entry>
                                Returns the cached schema object.
                                Net_LDAP2 will consider anything returned invalid, except a valid Net_LDAP2_Schema object.
                                In case you return a Net_LDAP2_Error, this error will be routed to the return of the
                                $ldap->schema() call. If you return something else, Net_LDAP2 will fetch a fresh
                                Schema object from the LDAP server and tries to cache it via <function>store</function>.
                                You may also want to implement a cache aging mechanism here too.
                            </entry>
                        </row>
                        <row>
                            <entry>storeSchema</entry>
                            <entry><classname>Net_LDAP2_Schema</classname> object</entry>
                            <entry><literal>true</literal> or (in special cases) <classname>Net_LDAP2_Error</classname></entry>
                            <entry>
                                Stores a schema object in the cache.
                                This method will be called, if Net_LDAP2 has fetched a fresh schema object from LDAP
                                and wants to init or refresh the cache. In case of errors you may return a
                                <classname>Net_LDAP2_Error</classname> which will be routet to the client.
                                Note that doing this prevents, that the schema object fetched from LDAP
                                will be given back to the client, so only return errors if storing of the cache is
                                something crucial (e.g. for doing something else with it). Normaly you dont want to
                                give back errors in which case Net_LDAP2 needs to fetch the schema once per script run and
                                use the error functionality of <function>loadSchema</function>.
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </para>
    </refsection>

    <refsection><info><title>Packaged schema cache classes</title></info>
        <para>
            As of Net_LDAP2 2.0.0, there is one default schema caching class: <classname>Net_LDAP2_SimpleFileSchemaCache</classname>.
            This cache class is built to be flexible yet simple to use and may serve as example to write own caching classes.
            This cache stores the schema object in a flat file. The path is freely configurable. It also servers a cache aging
            mechanism that can be used to invalidate the cached schema after some time so it will be refreshed regularly.
        </para>
        <para>
            To use this cache, you firstly need to initialize and configure a fresh cache object. Then the cache must
            be registered with the <classname>Net_LDAP2</classname> instance. After that, Net_LDAP2 will use the cache.
            <example><info><title>Initializing the SimpleFileSchemaCache</title></info>
        <programlisting role="php"><![CDATA[
$myCacheConfig = array(
        'path'    => '/tmp/Net_LDAP_Schema.cache',
        'max_age' => 1200 
);
$myCacheObject = new Net_LDAP2_SimpleFileSchemaCache($myCacheConfig);
$ldap->registerSchemaCache($myCacheObject);
]]></programlisting>
            </example>
        </para>
        <para>
            <table><title><classname>Net_LDAP2_SimpleFileSchemaCache</classname> config options</title>
                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Option</entry>
                            <entry>Mandatory?</entry>
                            <entry>Default</entry>
                            <entry>Description</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry><literal>path</literal></entry>
                            <entry>No</entry>
                            <entry><litral>/tmp/Net_LDAP_Schema.cache</literal></entry>
                            <entry>
                                The full path to the cache file. To improve the caches performance under linux,
                                you can place the cache file in a tmpfs mounted directory. This will put the file
                                in the computers memory instead on disk, enabling nearly instant access.
                            </entry>
                        </row>
                        <row>
                            <entry><literal>max_age</literal></entry>
                            <entry>No</entry>
                            <entry><litral>1200</literal></entry>
                            <entry>
                                Maximum cache age in seconds. The age of the cache is determined by the files
                                last change time. If <literal>max_age</literal> is reached, Net_LDAP2 will fetch
                                a fresh Net_LDAP2_Schema object which is then stored in the cache file again.
                            </entry>
                        </row>
                     </tbody>
                </tgroup>
            </table>
        </para>
    </refsection>

    <refsection><info><title>Writing own schema cache classes</title></info>
        <para>
            However this is basicly an easy task, this is beyond the scope of this manual. If you want to write your
            own custom schema cache, please refer to the detailed example at
            <literal>/your/pear/path/docs/Net_LDAP2/examples/schema_cache.php</literal> as well as the source/APIdoc of
            the interface <classname>Net_LDAP2_SchemaCache</classname>.
        </para>
    </refsection>

</refentry>