Putting It All Together (Technically)

Panl was not specifically designed to be web facing, although it could be should you so choose.  The recommended way is to hide the Panl implementation CaFUPs URL and proxy them through a web or application server.

A number of Panl servers can be spun up at the same time (on different ports of course) and load balanced between them.  There is no state to be kept between requests, so it is lightweight and fast.

A Brief Architecture



Image: The recommended approach to integrating the Panl server


In the above diagram, the request hits the front end web/app server, is proxied through to the correct Panl CaFUP which is then handled by a Collection Request Handler.  The URL path part is decoded and parsed, the query built, sent to the Solr server and the response built and returned.

You may wish to open the Panl server to external requests, however, be aware that there is no authentication or authorisation in the Panl server.  See the section on Is Synapticloop Panl For Me? to inform your decision.

Production Readiness

  1. Turn off in-build Panl testing URLs,
    Set the property     panl.results.testing.urls=false in the panl.properties file
  2. Turn off verbose 404 and 500 HTTP status responses,
    panl.status.404.verbose=false
    panl.status.500.verbose=false
  3. Finally, check the logging requirements (see heading below).
    Edit the     log4j2.xml file to your requirements.

Logging

Panl utilises the log4j/slf4j framework for all its logging and does not log excessively.  The parts of logging that Panl performs is:

  • INFO level startup logging which logs informational messages about the Panl configuration and URL bindings at startup,
  • DEBUG level logging for inbound Panl token decoding and validation,
  • DEBUG level logging for the query string that is passed through to the Solr server, and
  • Error level debugging for HTTP status 500 Internal Server Error (with stacktraces).

The most up-to-date logging file can always be viewed on the GitHub repository:

https://github.com/synapticloop/panl/blob/main/src/main/resources/log4j2.xml 

A copy of the file is included below:

01

02

03

04

05

06

07

08

09

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

<?xml version="1.0" encoding="UTF-8"?>

<!--

  ~ This is the default logging configuration file for the Panl server which

  ~ does not do too much.

  ~

  ~ Panl does not log too many things, just startup and the incoming requests

  ~ and validation

  ~

  -->

<Configuration status="WARN">

  <!--

  ~ This is the root logger which just logs the INFO messages to the

  ~ console, which are the generic startup messages.

  -->

  <Loggers>

    <Root level="info">

      <AppenderRef ref="console"/>

    </Root>

    <!--

      ~ The Panl request handlers log on the debug level for the incoming panl

      ~ token validation and the transposed Solr query that is executed.  To

      ~ remove this logging, comment out the following Logger, or just delete

      ~ it.

      -->

    <Logger name="com.synapticloop.panl.server.handler" level="debug"

            additivity="false">

      <Appender-ref ref="console" />

    </Logger>

  </Loggers>

  <Appenders>

    <Console name="console" target="SYSTEM_OUT">

      <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{2} - %msg%n"/>

    </Console>

  </Appenders>

</Configuration>

Setting the Logging Levels

The logging configuration file is located in the release package with the name PANL_INSTALL_DIRECTORY/lib/log4j2.xml.  

Generating SEO Friendly URLs

Going beyond the in-built features of the Panl configuration, generating URLs - especially those with a passthrough parameter requires.

You could either go to the datasource (e.g. a database) and build the URLs programmatically, or let Panl generate all of the URL paths and, or a combination of both.

Data Dependencies

Using the original datasource to generate links will create a dependency on the Panl configuration, and should the Panl configuration change, then the links may not still be valid.

For example, if you generated links for the mechanical pencils collection from a datasource as

/Manufactured+by+Koh-i-Noor+Company/b/

And the Panl configuration changed to generate the path:

/fine-pencils-by-Koh-i-Noor/b/

Then Panl would not return any results as the prefix and suffix did not match and this facet would not be passed through to the Solr server.

Passthrough URLs

Passthrough URLs are a little more able to withstand Panl configuration changes as they are not linked to any Solr field value.

Passthrough URLs are also best used to link to a single document, or a subset of documents.  For example, in the Book Store dataset, the following link uniquely identifies a book (using the ID field from Solr):

http://localhost:8181/panl-results-viewer/book-store/default/4/i/

And consequently any passthrough parameter will give the same result, such that

http://localhost:8181/panl-results-viewer/book-store/default/Michael+Connelly+The+Last+Coyote+-Harry+Bosch+Series/4/zi/,

and

http://localhost:8181/panl-results-viewer/book-store/default/This+is+not+a+link+to+a+book+but+returns+results/4/zi/

Return the same result.

When using passthrough URLs, you may wish to configure a separate file and associated CaFUP  just for these values, and be able to tweak other configured CaFUPs.

Handling Errors

You may also wish to return a 404 HTTP status code if the number of results returned is zero (0). To indicate to users and search engines that are scraping your site that this URL is no longer available.

~ ~ ~ * ~ ~ ~