-
- <para>
- Clients of the pazpar2 webservice interface can selectively override
- settings for individual targets within the scope of one session. This
- can be used in conjunction with an external authentication system to
- determine which resources are to be accessible to which users. Pazpar2
- itself has no notion of end-users, and so can be used in conjunction
- with any type of authentication system. Similarly, the authentication
- tokens submitted to access-controlled search targets can similarly be
- overriden, to allow use of pazpar2 in a consortial or multi-library
- environment, where different end-users may need to be represented to
- some search targets in different ways. This, again, can be managed
- using an external database or other lookup mechanism. Setting overrides
- can be performed either using the 'init' or the 'settings' webservice
- command (see XXX ref to pazpar2 protocol).
- </para>
-
- <para>
- In fact, every setting that applies to a database (except pz:id, which
- can only be used for filtering targets to use for a search) can be overriden
- on a per-session basis. This allows the client to override specific CCL fields
- for searching, etc., to meet the needs of a session or user.
- </para>
-
- <para>
- Finally, as an extreme case of this, the webservice client can
- introduce entirely new targets, on the fly, as part of the init or
- settings command. This is useful if you desire to manage information
- about your search targets in a separate application such as a database.
- You do not need any static settings file whatsoever to run pazpar2 -- as
- long as the webservice client is prepared to supply the necessary
- information at the beginning of every session.
- </para>
-
- <para>
- NOTE: The following discussion of practical issues related to session and settings
- management are cast in terms of a user interface based on Ajax/Javascript
- technology. It would apply equally well to many other kinds of browser-based logic.
- </para>
-
- <para>
- Typically, a Javascript client is not allowed to directly alter the parameters
- of a session. There are two reasons for this. One has to do with access
- to information; typically, information about a user will be stored in a
- system on the server side, or it will be accessible in some way from the server.
- However, since the Javascript client cannot be entirely trusted (some hostile
- agent might in fact 'pretend' to be a regular ws client), it is more robust
- to control session sesttings from scripting that you run as part of your
- webserver. Typically, this can be handled during the session initialization,
- as follows:
- </para>
-
- <para>
- Step 1: The Javascript client loads, and asks the webserver for a new pazpar2
- session ID. This can be done using a Javascript call, for instance. Note that
- it is possible to submit Ajax HTTPXmlRequest calls either to pazpar2 or to the
- webserver that pazpar2 is proxying for. See (XXX Insert link to pazpar2 protocol).
- </para>
-
- <para>
- Step 2: Code on the webserver authenticates the user, by database lookup,
- LDAP access, NCIP, etc. Determines which resources the user has access to,
- and any user-specific parameters that are to be applied during this session.
- </para>
-
- <para>
- Step 3: The webserver initializes a new pazpar2 settings, and sets user-specific
- parameters as necessary, using the init webservice command. A new session ID is
- returned.
- </para>
-
- <para>
- Step 4: The webserver returns this session ID to the Javascript client, which then
- uses the session ID to submit searches, show results, etc.
- </para>
-
- <para>
- Step 5: When the Javascript client ceases to use the session, pazpar2 destroys
- any session-specific information.
- </para>
-
- <refsect2><title>SETTINGS FILE FORMAT</title>
- <para>
- Each file contains a root element named <settings>. It may
- contain one or more <set> elements. The settings and set
- elements may contain the following attributes. Attributes in the set node
- overrides those in the setting root element. Each set node must
- specify (directly, or inherited from the parent node) at least a
- target, name, and value.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>target</term>
- <listitem>
- <para>
- This specifies the search target to which this setting should be
- applied. Targets are identified by their Z39.50 URL, generally
- including the host, port, and database name, (e.g.
- bagel.indexdata.com:210/marc). Two wildcard forms are accepted:
- * (asterisk) matches all known targets;
- bagel.indexdata.com:210/* matches all known databases on the given
- host.
- </para>
- <para>
- A precedence system determines what happens if there are
- overlapping values for the same setting name for the same
- target. A setting for a specific target name overrides a
- setting whch specifies target using a wildcard. This makes it
- easy to set defaults for all targets, and then override them
- for specific targets or hosts. If there are
- multiple overlapping settings with the same name and target
- value, the 'precedence' attribute determines what happens.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>name</term>
- <listitem>
- <para>
- The name of the setting. This can be anything you like.
- However, pazpar2 reserves a number of setting names for
- specific purposes, all starting with 'pz:', and it is a good
- idea to avoid that prefix if you make up your own setting
- names. See below for a list of reserved variables.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>value</term>
- <listitem>
- <para>
- The value of the setting. Generally, this can be anything you
- want -- however, some of the reserved settings may expect
- specific kinds of values.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>precedence</term>
- <listitem>
- <para>
- This should be an integer. If not provided, the default value
- is 0. If two (or more) settings have the same content for
- target and name, the precedence value determines the outcome.
- If both settings have the same precedence value, they are both
- applied to the target(s). If one has a higher value, then the
- value of that setting is applied, and the other one is ignored.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-