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 URL paths.

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 - this 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:

https://github.com/synapticloop/panl/blob/main/src/dist/sample/panl/mechanical-pencils/panl.properties 

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 page search 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.

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

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:

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.

Enabling The Panl Results Testing URLs

Controls whether the debugging and testing URLs are made available.

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:

1. http://localhost:8181/panl-results-viewer/,
2. http://localhost:8181/panl-results-explainer/, and
3. http://localhost:8181/panl-single-page-search/ 

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.

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.

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

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.

Setting HTTP Status Message Verbosity

Controls the message field of the JSON HTTP status response.

If set to false, the JSON object response will only ever have three keys:

1. error - will always be true
2. status -  will be either 404, or 500
3. message - will be either "Not found" or "Internal server error"

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.  For 404 errors, the JSON response object will include a list of valid URLs.

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.

• 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 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.

~ ~ ~ * ~ ~ ~