XPASearch Version 2.2 December 2004 New features since XPA 2.1 -------------------------- Hit-Level Authentication ------------------------ XPA 2.2 now includes the Search Search functionality previously supported by the deprecated package com.ultraseek.xpa.security (last distributed with xpasecurity-2.0.0.jar). See the sample file SSOSearchServlet.java for an example of how to deploy secure search with Hit-Level authentication with your site's security system. Query Logging ------------- XPA 2.2 supports user-level query logging. The UltraseekServer class provides a method "logQuery" to log a query to a running Ultraseek instance. This feature requires Ultraseek version 5.3.3 or above, or contact Technical Support to obtain a patch that can be applied to older versions to enable the feature. An example of using the logging feature can be found in the sample files SearchServlet.java and QueryLogging.java. These files can be found in the "samples" directory. Diagnostic Logging ------------------ XPA 2.2 requires the Jakarta Commons Logging package for internal diagnostic logging. You must deploy commons-logging.jar with your application, even if you do not make use of diagnostic information. commons-logging.jar is available from: http://jakarta.apache.org/commons/logging/ XPA 2.2 has been tested with version 1.0.4 An example of turning activating XPA diagnostic logs can be found in the sample file DiagnosticLogging.java. Ultraseek development recommends the following diagnostic levels: info For production deployment debug During your development trace For very verbose logging during development Ultraseek Versions supported ---------------------------- Ultraseek and XPA versions are designed to be compatible for features that are in common. For example, UltraseekServer.search() will work with any version of XPA and any version of Ultraseek after 3.1. However, SpellServer requires at least XPA version 2.1 and Ultraseek version 5.0 as those are the earliest versions that support the feature. XPA 2.2 has been extensively tested with the most current patch releases of Ultraseek 5.3 and Ultraseek 5.2. XPA 2.2 has been spot-checked with Ultraseek releases prior to 5.2. There are known problems using XPA with Ultraseek 5.3.0 - which were fixed for Ultraseek 5.3.1. JDKs Supported -------------- XPASearch 2.2 supports JDK 1.3, JDK 1.4, and JDK 5.0. Additional packages required (for all JDK versions): Jarkarta Commons Logging (for XPA diagnostic logs) commons-logging.jar Version: 1.0.4 (tested version, earlier should be OK) Obtained from: http://jakarta.apache.org/commons/logging/ For LDAPSearchable: ldapjdk.jar from Netscape Directory SDK for Java version 4.1 http://www.mozilla.org/directory/javasdk.html For Servlet sample files: servlet.jar from Java Servlet Specification 2.2 or higher http://java.sun.com/products/servlet/ Download either J2EE 1.3.1 (Servlet 2.3) or J2EE 1.4 (Servlet 2.4) For QuickLinksSearchable: xercesImpl.jar (SAX2 XML Parser Implementation) http://xml.apache.org/xerces2-j/index.html (download Xerces-J-tools.2.3.0 or higher) Since the parser class is loaded dynamically, in JDK 1.4 it may be necessary for you to install the XML Parser into: $JAVA_HOME/jre/lib/endorsed/ Note: Sample file SearchQuickLinks.java is useful for debugging problems with QuickLinksSearchable locating the XML Parser. Additional packages required (JDK 1.3 only): For communication with an Ultraseek Server via HTTPS: jnet.jar, jsse.jar, and jcert.jar from the Java Secure Socket Extension Library. http://java.sun.com/products/jsse/index-103.html (Find download button near the bottom of the page) For QuickLinksSearchable: xml-apis.jar (Definition of SAX2 XML Parser APIs) http://xml.apache.org/xerces2-j/index.html xml-apis.jar (download Xerces-J-tools.2.3.0 or higher) Additional changes in XPA 2.2 ----------------------------- HTTPClient: XPA now sets the User-Agent HTTP header to "Ultraseek-XPA/", (for example: Ultraseek-XPA/2.2.0). The previous setting was "Verity Ultraseek XPA", which does not conform to HTTP standards. Javadoc for the API and the Sample files have been integrated. New features in Sample files ---------------------------- DebugServlet now sorts debugging information by property name. AddDocument sample file has been clarified. New Sample files ---------------- SSOSearchServlet demonstrates how to implement a secure search interface with Single-Sign-On and Hit-Level authentication within your network environment. DebugAccessGuard is for use with SSOSearchServlet to help with development of your secure search. PragmaticHTTPAccessGuard is a version of HTTPProxyAccessGuard with solutions for old document servers. SecureFilterSearchable demonstrates a Searchable that removes SearchResults that throw SecurityException. ShowServerInfo gives diagnostic configuration information on an Ultraseek server. QueryLogging demonstrates how to log queries done in XPA to an Ultraseek instance. CommonsQueryLog is an example implementation of the QueryLog interface that sends log entries to the Jakarta Commons Logging component. CommonsQueryLogging is a runnable example of how to use CommonsQueryLog. DiagnosticLogging demonstrates how to configure the JDK 1.4 java.util.logging package to receive various diagnostic logging messages that XPA generates. New Classes ----------- com.ultraseek.xpa.search: HTTPProxyAccessGuard -- Tests for permitted access to a SearchResult by using HTTP HEAD or GET on the referenced URL. New Interfaces -------------- com.ultraseek.xpa.search: HTTPResponseWrapper -- A view of an HTTP response QueryLog -- Logs user queries with result counts New Methods ----------- com.ultraseek.xpa.search: AbstractGuard.clear() -- Clear the cache of security check results. AbstractGuard.getKey(SearchResult) -- Key for caching of security check results. GuardingSearchResultList.getAllowedSize() GuardingSearchResultList.getDisallowedSize() GuardingSearchResultList.getPendingSize() -- Return the number of SearchResults which are allowed, disallowed, and pending authorization. com.ultraseek.xpa.server: UltraseekServer(URL) -- Constructs an UltraseekServer using protocol, host, and port from a URL. UltraseekServer.getURL() -- Returns UltraseekServer's protocol, host, and port in URL format. UltraseekServer.logQuery() -- Logs a query to the remote Ultraseek Server query log CollectionAdmin.getConfiguration CollectionAdmin.getConfigurationAsString CollectionAdmin.updateConfiguration ServerAdmin.destroyCollections -- The above methods are primarily for the support of automated Ultraseek testing. New Methods that require Ultraseek server 5.3.3 ----------------------------------------------- UltraseekServer.logQuery() -- Logs a query to the query log file of an Ultraseek server. Behavior Changes ---------------- AbstractGuard now caches the result of a security check by the URL of the SearchResult. Previously the entire SearchResult object was used as the cache key. Use AbstractGuard.getKey() to change the caching behavior. AbstractGuard.checkGuardUncached() is now allowed to throw IOException. An IOException will cause checkGuard to throw a SecurityException to deny access, but the SecurityException will not be cached -- allowing for retry when the Security system is non-responsive. Deprecations ------------ com.ultraseek.xpa.search.AbstractGuard.clone(): com.ultraseek.xpa.search.AccessGuard.clone(): Cloning of cached security information creates a security hole. Create a new instance, instead of cloning an existing instance. com.ultraseek.xpa.security.*: The entire package, previously shipped with xpasecurity.jar, has been deprecated. See XPA 2.2 Sample/SSOSearchServlet.java and com.ultraseek.xpa.search.HTTPProxyAccessGuard for replacment technology. Known Issues ------------ KeywordSearchable and QuickLinksSearchable do not perform Unicode character normalization before matching query terms with keywords. There are unexpected side-effects when using XPA to search an Ultraseek 5.3 server which has activated server-controlled Hit-Level-Filtering. In particular, SearchResultList.getResultCount() will always return 0 as the Ultraseek server will not reveal the number of matching documents when Hit-Level-Filtering is active. We recommend turning off Ultraseek's Hit-Level-Filtering, and perform all secure searches using Ultraseek XPA. Bug Fixes: ---------- [BZ192] XPA now generates a diagnostic error message for a QuickLink defined on the Ultraseek server with a malformed URL. [BZ227] The Ultraseek query language keywords AND, OR, and NOT are now supported by Query.parse() [BZ577] Solved OutOfMemoryError when searching with locale unsupported by Ultraseek server (example: Hungarian) [BZ657] ScoreUsingDateSearchable was ignoring dates younger than 128 days. [BZ665] SpiderStatus.getNumIndexedDocuments() always returned 0 (also ScannerStatus) [BZ692] DedupingSearchable and EditorialSearchable were not reducing SearchResultList.getResultCount() as duplicates were removed. Bug Fixes which require an updated Ultraseek server: ---------------------------------------------------- [BZ538] XPA prior to 2.1.2 reports 'unknown compression method' when connecting to Ultraseek 5.3.0 [fixed in Ultraseek 5.3.1]. [BZ547] SearchResult descriptions for queries "containing phrases" were not being highlighted [fixed in Ultraseek 5.3.3]. SearchServlet: -------------- [BZ395] A QuickLink without a title now displays its URL (method: showQuickLinksSearchResult). [BZ435] Ellipsis (...) was unnecessarily appearing before each highlighted term in the description of a search result (method: printDescription). [BZ767] SearchServlet will now display "No more results available" when st is set beyond the end of the SearchResultList (method: showNoMoreResults). [BZ775] Fixed formatting of HTML table containing the "extra" metadata for a SearchResult (method: showOneHitExtraInformation). Other SearchServlet fixes (no bug numbers): "Show individual word scores" is now implemented for the Advanced search form. col, ws, and sc query parameters are now "sticky" parameters on search URLs generated inside the search results page. UI translations updated for Finnish and Japanese. Fixed bugs in support of "pw" (page width) style setting. The display of each SearchResult is now an individual one-row table. Previously each result was one row in a multi-row table. Using individual tables results in a faster browser display when nh (number of hits) is large. Hidden form variables are only emitted if their value is different from the default for the current display style. XPA Version 2.2.0: First release.