The panl.properties Configuration File
The panl.properties file controls
- which Solr server to connect to,
- which client to use, and
- the bindings of the Solr collections to Panl Collection and FieldSet URL paths (CaFUPs).
By default, upon startup, the Panl Server will look for a file named panl.properties in the same directory that the server was started. Alternatively, you can pass through a -properties command line argument with the value being the location of the properties file - the location of this file will then become the base directory for ALL referenced properties files in the panl.collections.<field_set> property.
The file is included in the release package, or, for an overly commented online format:
|
Note: The above link is for the most up-to-date file, including new feature developments. To view the file for the version that you are using, use the tag that matches the version that you are using and browse the code. See https://github.com/synapticloop/panl/tags for the version that you are using, and https://github.com/synapticloop/panl/tree/1.0.0 to view the source (This link will view the source at version 1.0.0). |
The panl.properties file defines the following properties:
- solrj.client
The SolrJ client to use to connect to the Solr server, the selection of client will impact whether the solr.search.server.url is a single URL, or a comma separated list of URLs, or even a zookeeper comma separated list of URLs - solr.search.server.url
The URL, or comma separated URLs for the Panl server to connect to (including options for zookeeper related connections) - panl.results.testing.urls
Whether to enable the testing URLs which will help you understand and debug the Panl LPSE URL paths, and provide a single search page user interface - panl.status.404.verbose
Whether to enable a verbose 404 HTTP status error message - panl.status.500.verbose
Whether to enable a verbose 500 HTTP status error message - panl.collection.<solr_collection_name>
The list of properties files to load collections and field sets to serve
Configuring The SolrJ Connector
Set the implementation of the SolrJ connection.
01 02 03 04 |
#solrj.client=Http2SolrClient #solrj.client=HttpJdkSolrClient #solrj.client=LBHttp2SolrClient solrj.client=CloudSolrClient |
|
IMPORTANT: This is a __MANDATORY__ property, and the Panl server will not start if it is missing. |
Panl uses the SolrJ connector to communicate with the Solr server, which MUST be one of the following implementations:
- Http2SolrClient
- HttpJdkSolrClient
- LBHttp2SolrClient
- CloudSolrClient
The property solrj.client controls which SolrJ implementation is to be used. There is a one to one mapping of property values to Solr client values in the package org.apache.solr.client.solrj.impl (NOTE: that some of the implementations are deprecated, and are not included in the list of possible values).
All values are included in the panl.properties file, with all but the last commented out.
Setting The Solr Server URL(s)
Set the URL, or URLs for the Solr server
01 |
solr.search.server.url=http://localhost:8983/solr,http://localhost:7574/solr |
|
IMPORTANT: This is a __MANDATORY__ property, and the Panl server will not start if it is missing. |
The solr.search.server.url contains the URL, or comma separated list of URLs for the underlying Solr server to connect to.
The defaults are set in the panl.properties file for the example cloud as below.
solr.search.server.url=http://localhost:8983/solr,http://localhost:7574/solr
For cloud based Solr server installations (including the one in this book), you may also use the zookeeper URLs.
Zookeeper URLs MUST start with a zookeeper: prefix (including the colon :). For the implementation contained in this book the property would be set as:
solr.search.server.url=zookeeper:http://localhost:9983
The Solr documentation states that
The ZooKeeper based connection is the most reliable and performant means for CloudSolrClient to work. On the other hand, it means exposing ZooKeeper more broadly than to Solr nodes, which is a security risk. It also adds more JAR dependencies.
(added emphasis by the author)
Testing this configuration in this book has shown that this implementation is slower by an order of magnitude. However, your implementation, hardware, and server setup may provide different results.
|
IMPORTANT: If the CloudSolrClient is configured as the SolrJ client with zookeeper URLs then you __SHOULD__ test the speed of results generation with and without the zookeeper
In testing for this book, the zookeeper URLs were an order of magnitude slower than using the direct Solr URLs. Testing of the two configuration types is __DEFINITELY__ recommended.
Zookeeper configuration does have the advantage of knowing which Solr instances are available and which ones to connect to, so choose wisely. |
Enabling The Panl Results Testing URLs
Controls whether the debugging and testing URLs are made available.
01 |
panl.results.testing.urls=true |
The testing URLs provide simple web applications to help with understanding and debugging the Panl LPSE paths and configuration.
If enabled (i.e. set to true), the following web apps will be made available:
- http://localhost:8181/panl-results-viewer/,
- http://localhost:8181/panl-results-explainer/, and
- http://localhost:8181/panl-single-page-search/
|
IMPORTANT: If this property is set to true, then in the unlikely event that you have a collection named panl-results-viewer, panl-results-explainer, or panl-single-page-search, the results may be indeterminate. If you use the Panl generator, you will not be able to generate configuration files that start with the string panl-. |
If this property does not exist, or does not exactly (case sensitive) equal the String value true, then the above URLs will not be registered to respond to any queries.
|
IMPORTANT: It is recommended to set this property to false for production use, and the only property value that will enable this is the case sensitive value true. |
The Panl Results Viewer
A simple[15] results viewer allowing you to browse all features and functionality of the Panl server.
Image: The In-Built Panl Results Viewer web app showing the list of available collection/FieldSet configurations and a working faceted search interface.
Select one of the available CaFUPs links, which will then allow you to search and facet and see the results.
This page will also console.log debugging information and the returned objects to the browser console.
The Panl Results Explainer
A simple[16] results explainer detailing how a Panl LPSE URL is parsed and decoded. It also provides an overview of the configuration for the specific collection.
Image: The In-Built Panl Results Explainer web app showing the list of available collection/fieldset configurations
Select one of the available CaFUPs links, which will then present the configuration for that particular CaFUP.
The Panl Single Page Search
An example of a single page search interface which will allow you to see all facets, select them, and see the results in the results viewer.
Image: The In-Built Panl Single Page web app showing the list of available collections.
Select one of the available Collection links, which will then present all of the available facets in a single page search interface.
Setting HTTP Status Message Verbosity
Controls the message field of the JSON HTTP status response.
01 02 |
panl.status.404.verbose=false panl.status.500.verbose=false |
If set to false, the JSON object response will only ever have three keys:
- error - will always be true
- status - will be either 404, or 500
- message - will be either "Not found" or "Internal server error"
01 02 03 04 05 |
{ "error":true, "status": <status_code>, "message": <message> } |
If this property is set to 'true' then the message will be more verbose, including a Java stack trace if there was a back end exception (i.e. an HTTP 500 status code). For 404 errors, the JSON response object will include a list of valid URLs.
|
IMPORTANT: It is recommended to set both of these properties to false for production use |
Binding Solr collections to Panl URL paths
The panl.collection.<solr_collection> property controls which Solr collections to bind and which Panl URL paths to serve them on.
panl.collection. |
<solr_collection> |
= |
path/to/file/ |
<panl_collection_url> |
.panl.properties |
The property key prefix |
The Solr collection |
|
The file path |
The filename prefix and Panl URL path |
The extension |
- The property key prefix - The Panl server will look for this prefix to load properties files
- The Solr collection is the search index to connect to on the Solr search server.
- File path - the file path is relative to the panl.properties file
- Filename prefix - This is the URL path that the Panl server will bind to
- The extension does not have to be .panl.properties - it may be anything provided that the file format is a Java .properties format
In the example src/main/panl/mechanical-pencils/panl.properties file, the property is set as:
panl.collection.mechanical-pencils=src/dist/sample/panl/mechanical-pencils/mechanical-pencils.panl.properties
Which will serve up the results from the Mechanical Pencils Solr search collection on the Panl URL path of /mechanical-pencils/*, where the asterisk is the FieldSet to be returned.
~ ~ ~ * ~ ~ ~