$Id: Changes,v 1.75 2008-04-30 17:27:56 mike Exp $

Revision history for Perl extension Keystone::Resolver.

1.23 Thu May 1 10:26:03 BST 2008

• Same as 1.22, except that it is properly date-stamped.

1.22 (IN PROGRESS)

• Oracle back-end now fully functional and tested, both with the resolver itself and the Admin UI. See db/README for instructions on making a toy Oracle resource database, and the top-level README for instructions on running the test-suite against this.
• Various changes to canonicalise the order of things like equal-priority results in the XML returned from resolve_to_xml(), required so that the same regression-test suite can be used with both MySQL and Oracle.
• Add a test-script that invokes the actual "resolve" script. The absence of this was responsible for 1.20 going out while "resolve" itself was still not making its own $resolver object, while the various test-scripts were.
• It is now mandatory to pass a $resolver into OpenURL::newFromCGI(), since memory problems will always result if it is allowed to allocate its own.
• Change API of OpenURL::newFromCGI() to reflect mandatory $resolver and better match the default constructor, new().
• Add Makefile.PL dependency on Scalar::Util.pm

1.21 Thu Apr 10 15:23:53 BST 2008

• URGENT BUGFIX RELEASE: the resolve script now makes its own $resolver object rather than allowing newFromCGI() to make one on its behalf. This ensures that the resolver stays referenced (not only by the OpenURL's weak reference) until the resolution is complete.

1.20 Thu Apr 10 12:36:28 BST 2008

• Changes to memory management: since the Resolver, Database, OpenURL and ContextObject classes all contain references back and forth, the next of mutually referencing objects was not getting destructed when it went out of scope, leading to memory exhaustion in long-running processes such as Apache servers under heavy load. That is now fixed through the use of weak references back to the "owning" objects. Tests show that resolving 50,000 OpenURLs does not cause noticable process growth.
• Changes to regression-test suite to facilitate running when not connected to network.
• Added new test script, admin.t, testing the code that underlies the web-based admin interface.
• Refactored database-access code in Database.pm, greatly reducing the number of similar functions and unifying logging.
• Add support for the Serial Alias object type, both in the code and in the Admin web UI. (Admin support for this is not very useful yet, since, as with other kinds of link, there is no way to maintain the links between an alias object and the serial that it is an alias of.)
• Added low-level object-API support for the service-to-serial and genre-to-servicetype link tables. (There's no point in wiring them into the Admin UI, since they contain no information other than link IDs.)
• Search-result listing in Admin web UI does not offer links to sort on virtual fields.
• Search-result listing in Admin web UI restored to being valid XHTML 1.0.
• Top-level "resolve" script runs within a scoped block, to ensure that all local ("my") variables go out of scope when the script ends, whatever Apache's memory management regime may be. This contributes to fixing a memory-exhaustion problem.

1.19 Wed Mar 26 17:22:50 GMT 2008

• Use the DBI module's connect_cached() method to pool similar connections. This is important when running the resolver as a web-service, since (currently) each invocation makes a new Resolver object, which in turn makes its own Database object, which until this change made its own DBI connection. Due to Perl's lazy garbage-collection, each Apache process can accumulate a lot of these connections before they get tidied up, and when (as is usually the case) many Apache processes are used, they can exhaust the back-end database's connection pool.
• Log-levels (as specified for example by the opt_loglevel query parameter) can now be specified symbolically, as a comma-separated list of level names, as well as numerically.
• New logging level, LIFECYCLE, notes the creation and destruction of Resolver, OpenURL and Database objects.
• The DBI logging level can now also be set, using the opt_dbi_trace query parameter.
• New function LogLevel::num() that converts a logging-level string into a numeric value, complementing the existing label(). Both these functions now handle composite values (e.g. CONVERT01|LIFECYCLE).
• New test-script for log-level utility functions.
• Add brief documentation of logging (doc/logging).
• Option setting is now always done via the option() method rather than, as previously at Resolver creation time, via direct assignment. This ensures that the logging-related special cases are handled uniformly.
• Add static_log() function (not method) to the Resolver class, for use in contexts where no Resolver object is available to invoke the method on.
• Copies are included (web/htdocs/1cate-test/) of the KEV context-objects that were part of Openly's OpenURL 1.0 test suite. These will be useful one day for local testing.
• More explicit diagnostics for some database problems.
• Steps towards support for Oracle as the back-end database: NOT YET COMPLETE.

1.18 Mon Feb 11 11:05:16 GMT 2008

• Add the ability to delete resource database objects from the Admin UI.

1.17 Thu Feb 7 16:26:37 CET 2008

• Fix character-set handling AGAIN :-) The resolver library was correcting accepting any specified character encoding and correctly outputting UTF-8 with the necessary XML and HTML specifications to sayt that's what it was doing, but the top level resolver script was telling Perl to do UTF-8 encoding on output. (Why didn't that cause problems when running under Apache 1/mod_perl 1? Because of the character-set faries.)
• Generalise rewrite rule so that /resolve/<dbname> URLs are correctly interpreted. This provides an easy means for running against alternative resource databases.
• Fix sorting in Admin UI such that it works through successive pages of results.
• When editing an object in the web-based Admin UI, drop-down option lists that are populated from the database (e.g. the service-types that a service can belong to) are now sorted.
• Fix a bug in editable_fields(), which was omitting from its output those fields used as links to non-dependent sets (e.g. the set of services implementing a service-type) rather than dependent sets (e.g. the one service-type to which a service belongs). The result of that bug was that, for example, the raw numeric service_type_id was included on the service editing page as well as the service-type name. No more.
• The resolver now responds more politely if an attempt is made to access a virtual site not supported by the database, and points the user at a new README file that explains the situation.
• The service_type table now includes a new "plugin" field which can be used to explicitly specify the name of the Perl plugin to use to implement services of that type, if the required plugin is not named the same as the tag of the service-type. This allows multiple service-types to share the same plugin. (When this field is empty, the plugin named after the service-type's tag is used, as before. Thus the new field is only an override mechanism, and the new arrangement is backwards compatible.)
• A database patch script is made available to support the new service_type.plugin field: see db/updates/
• When building URIs from recipes, the resolver now, correctly, accepts the first of several slash-separated candidate fields whose value is defined and non-empty, whereas before it would accept defined but empty values.

1.16 Tue Feb 5 02:57:05 GMT 2008

• Remove advisory dependency on Apache module from Makefile.PL, as the true dependency is now on EITHER Apache or Apache2, and there is no way to specify that in the PREREQ_PM clause.
• Modification to how the sample database is built result in a more flexible configuration.
• Both the resolver itself and the Admin UI issue more a polite, informative message if the Resource Database is not there.
• Documentation tweaks arising from merge of Apache2 CVS branch back into head.
• README describes public CVS archive, Debian installation procedure and service-names in the default resource database.

1.15 Mon Jan 28 12:26:37 GMT 2008

• Fix error in Apache2 debian-package configuration file: mod_rewrite's log was written into /var/log/apache rather than /var/log/apache2, which causes Apache2 to refuse to start if Apache 1.x is not also installed.
• Comments in Makefile.PL indicate what Debian packages contain each of the prerequisite Perl modules.

1.14 Mon Jan 28 10:49:04 GMT 2008

• Fix the resolver-site's index page to correctly state the baseURL. (No functional changes.)

1.13 Thu Jan 24 18:07:56 GMT 2008

• Small changes to Web configuration to allow Apache 1.x and Apache 2.x installations to co-exist, and to ensure that a Debian install can live side-by-side with a development version. (Yes, this means that you can -- and I do -- run four instances of the resolver on a single computer.)

1.12 Thu Jan 17 15:50:00 GMT 2008

• Support for running under both Apache 1.3/mod_perl and Apache 2.0/mod_perl2.
• Add utility function apache_request() and mod_perl_version() to Keystone::Resolver::Utils to support Apache-version independence.

1.11 Mon Dec 17 11:57:16 GMT 2007

• Fix bug #1967, which prevented the creation of certain types of record, including Service and User.

1.10 Thu Dec 13 17:27:15 GMT 2007

• Hardwired username/password pairs for read-only and read-write pairs removed from code. These are now obtained from the KRuser, KRpw, KRrwuser and KRrwpw environment variables.
• Set KRuser et al. in web/conf/apache1.3/debian.conf
• Set KRuser et al. in t/regression.t
• Fixes to the admin system's new-record-creation and editing system.

1.09 Mon Dec 3 09:46:22 GMT 2007

• Add documentation to bin/kr-recipe.
• Remove the obsolete PHP-based Web Admin UI from web/htdocs/dbadmin/
• Much better Debian packaging.

1.08 Fri Nov 23 18:23:00 GMT 2007

• Debian packaging. Currently encompasses the Perl part of the application only (libraries and driver scripts). A separate Debian package will follow for the Web Admin UI and the main HTTP entry point.

1.07 Fri Sep 21 10:00:40 BST 2007

• The "deny" boolean field of rule object (both service-type and service rules) is re-cast as an enumeration called "action", with values "include" and "exclude". This is clearer exposition, and better represents the code. The underlying database field is still called "deny" and still uses the boolean values 0 and 1, so no database changes are necessary.

1.06 Thu Sep 20 18:50:54 BST 2007

• Correct implementation of rules: both at the Service-Type and Service levels, and both "include" and "exclude" rules.
• Default options for the resolver object may now be set from the environment (though they will be overridden by opt_* keys in the OpenURL being resolved). The KR_OPTIONS environment variable is consulted: it consists of zero or more assignments, separated by commas, each of the form <option>=<value>: for example, "loglevel=32,xml=1". This is useful when running tests from the command-line.

1.05 Thu Sep 13 11:00:25 BST 2007

• Genre class includes backlink field "metadata_formats", which is included in its full display.
• Provides class includes backlink field "services", which is included in its full display.
• Add "browse" links for each object type as well as "search" in the Admin UI menu-panel.
• The example form web/htdocs/mod_perl/form2.html now includes a link to the Admin UI.
• ... and the home page of the Admin UI links to the form.

1.04 Thu Sep 13 00:50:30 BST 2007

• Change all occurrences of "media format" into "metadata format": the gormer was a mistake.
• Add links in admin UI to create new records as well as editing existing ones.
• Extend database with rules for selecting service-types and individual services based on values of fields in the OpenURL itself -- for example, when rfc.dctype=audiobook, omit online bookstores.
• Add database classes and Web UI for managing both kinds of rules.
• Better data-dictionary support for Domain (add name), Service (do not display ID field) and User (make summary-list name a link to full record).
• Web UI can now handle editing booleans and links (using dropdowns, which will not scale well when using large lists). This works ONLY FOR -TO-ONE LINKS and not for -to-many links.

1.03 Thu Jul 12 12:44:30 BST 2007

• _makeURI() now understands fallback fieldnames: for example, the sequence %{jtitle/btitle/title} will use jtitle if that is defined, otherwise %btitle if that is defined, otherwise plain title.
• Added a test-script for _makeURI().
• Added a new log-level, WARNING.
• Changed OpenURL::warn() to use $this->log(WARNING).

1.02 Tue Jul 10 12:45:06 BST 2007

• Admin UI work continues.
• Add service for linking into MasterKey.
• Add service for linking into Reindex.
• Add various hacks in identifier plugins to cope with the nasty COinS OpenURLs generated by WorldCat.

1.01 Fri May 25 09:35:08 BST 2007

• Add configuration-file fragment for Apache 2.0.x.
• Changed the format of the XML document generated internally as part of the resolution process (and available to the user by providing the opt_xml query argument as part of the OpenURL). The new format places the text of each candidate result as CDATA rather than an attribute value, opening the way for more complex values.
• Updated the XML DTD for the results format to reflect this format change: etc/constraint/results-1.0.dtd
• Updated the various XSLT stylesheets in etc/xslt to work on the new form of the results XML.
• Updated the test regression-test's known-good output to match the new XML format.
• Recipe rendering by Keystone::Resolver::OpenURL::makeURI() now accepts additional optional pre-special flag "" which results in the interpolated value being stripped of spaces.
• Add new command-line utility bin/kr-recipe to test recipe rendering.
• Correct handling of character sets.
• Add admin UI: this affects Apache configuration, the core library, many HTML::Mason components, etc. Not complete yet.

1.00 Fri Jan 26 17:18:37 GMT 2007

• original version; created by h2xs 1.23 with options

  -X --name=Keystone::Resolver --compat-version=5.8.0 --omit-constant --skip-exporter --skip-ppport

• Actually, the core of the code is much older than this, but Release 1.0 constitutes a complete repackaging and reorganisation, based on this h2xs invocation. This allows us to take advantage of the Perl packaging conventions to make the entire distribution, as well as a generally cleaner project layout. Prior releases were as a Perl module just called "Resolver" (which for that reason would not have been eligible as a CPAN module -- a two-level name is required). Earlier entries in this file describe that old structure.

Revision history for Perl extension Resolver.

0.03 (NOT RELEASED)

• "make test" now works on Red Hat 9, despite that platform's inability to load DBD::mysql non-lazily, i.e. when PERL_DL_NONLAZY is set. This is done by hackery in Makefile.PL to prevent PERL_DL_NONLAZY from being set, which is not really a good solution.
• Move citation generation, full-text reference generation and abstract generation from Resolver::OpenURL into their own plugins.
• Refine service plugin interface so that the result can be success, no-op, error or non-fatal error.
• New test-case that checks for unknown journal titles being properly diagnosed.
• Add ability to request a single service rather than the usual menu using svc_dat=indexdata:<service-type>:<tag>. Add new test-case "feature-single" that exercises this.
• Add ability for an OpenURL object to render itself as a version 1.0 OpenURL string. Among other uses, this functions as a v0.1-to-v1.0 converter.
• Add support for generating Endnote-style citations.
• Add ability for a ServiceType or individual Service plugin to specify the MIME-type of its result.
• Result sets consisting of a single, explicitly requested, result are now returned from Resolver::OpenURL::resolve() as self-contained objects of the specified MIME-type rather than embedded in a larger XML or HTML document. This allows the resolver to generate binary objects such as Endnote citations for download.

0.02 Fri Jul 30 02:23:34 2004

• First nailed-down version. This is not yet ready for public release, but it does follow CPAN-like conventions, and passes its own test-suite using the standard sequence "perl Makefile.PL && make && make test", so I am treating this as a baseline from which to describe future changes.

0.01 Wed Jul 28 16:00:52 2004

• original version; created by h2xs 1.22 with options

  -A -X -b 5.6.0 Resolver In fact, this Perl-module superstructure was retro-fitted to a project that had already undergone a great deal of development prior to the h2xs-ization.