jlog 5.1.0 API
The electronic log book client API allows programmers to easily add the ability for their programs to make log entries.
Usage
In order to use the library you need to include it in the classpath of your Java program. The software is packaged with Maven and available from https://github.com/JeffersonLab/jlog.
You need to have a client certificate to make direct submissions to the server. JLab users can obtain a certificate from the server at the following URL: https://logbooks.jlab.org/cert
You need to save the PEM formatted certificate as .elogcert in your home directory (or else be prepared to explicitly instruct the library where you saved the file if not in the default location). If you install the certificate in the certificate store used by your web browser you can verify the logbook server accepts it by navigating to: https://logbooks.jlab.org/authtest/
Note: JLab staff on JLab computers may have a certificate already in your home directory placed there by a system administrator for you.
Example Program 1: Hello World
public static void main(String[] args) throws LogException {
LogEntry entry = new LogEntry("Hello World", "TLOG");
long lognumber = entry.submitNow();
System.out.println("Successfully submitted log entry number: " + lognumber);
}
Tags: https://logbooks.jlab.org/tags
Logbooks: https://logbooks.jlab.org/logbooks
References: https://logbooks.jlab.org/references
Enumerations: http://logbooks.jlab.org/schema/TypeDefinitions.xsd
Configuration
A Java properties file is used to set configuration. A default file is included inside the jar.
To override defaults create a file named jlog.properties in your home directory with
desired overrides. Alternatively you can use the
Library.setConfiguration method to override the
properties. The properties include:
- LOG_ENTRY_SCHEMA_URL
- The URL to the log entry schema.
- COMMENT_SCHEMA_URL
- The URL to the comment schema.
- SUBMIT_URL
- The URL to submit (HTTP PUT) entries and comments to the log book server.
- FETCH_URL
- The URL to fetch (HTTP GET) log entries and comments.
- QUEUE_PATH
- The path on the local workstation (usually a network file share) to drop (queue) log entries and comments. If this property is missing or empty then the library will attempt to detect whether the program is running on Windows or UNIX and use the default value for the OS type, as defined in DEFAULT_UNIX_QUEUE_PATH and DEFAULT_WINDOWS_QUEUE_PATH.
- DEFAULT_UNIX_QUEUE_PATH
- The default file path to queue files if the QUEUE_PATH property is undefined and the library determines that it is running on a UNIX system.
- DEFAULT_WINDOWS_QUEUE_PATH
- The default file path to queue files if the QUEUE_PATH property is undefined and the library determines that it is running on a WINDOWS system.
- ATTACH_SINGLE_MAX_BYTES
- Maximum number of bytes allowed in a single attachment file.
- ATTACH_TOTAL_MAX_BYTES
- Maximum number of bytes allowed across all attachments.
- IGNORE_SERVER_CERT_ERRORS
- For testing it is often useful to ignore self signed certificates such as those used on logbooktest.acc.jlab.org.
Attachment Size Limits
Client-side size limits on attachments are enforced to help avoid an OutOfMemoryError or rejection by the server due to crossing the server attachment limit. The checks are performed when the addAttachment method is called or when creating a LogEntry from an XML file.
By default these limits are much lower than the limits if using the C++ implementation. The reason is because the default maximum heap size in Java is often 64MB. If you increase the limits here then be sure to bump up your JVM limit as well. For example, the command to execute Java with a max heap of 512 MB is: "java -Xmx512m".
The server may send a LogEntry or Comment back to the client which references attachments (via URLs) which are larger than these limits. The library will download all of the attachments to verify they are within the client limits.