aboutsummaryrefslogtreecommitdiffstats
path: root/reference/logging-slf4j
diff options
context:
space:
mode:
Diffstat (limited to 'reference/logging-slf4j')
-rw-r--r--reference/logging-slf4j/README.md50
-rw-r--r--reference/logging-slf4j/pom.xml91
-rw-r--r--reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogAdapter.java611
-rw-r--r--reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogConstants.java253
-rw-r--r--reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/package-info.java32
-rw-r--r--reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterOutputTest.java162
-rw-r--r--reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterTest.java387
-rw-r--r--reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogConstantsTest.java133
-rw-r--r--reference/logging-slf4j/src/test/java/testng.xml8
-rw-r--r--reference/logging-slf4j/src/test/resources/logback.xml35
10 files changed, 1762 insertions, 0 deletions
diff --git a/reference/logging-slf4j/README.md b/reference/logging-slf4j/README.md
new file mode 100644
index 0000000..2796a21
--- /dev/null
+++ b/reference/logging-slf4j/README.md
@@ -0,0 +1,50 @@
+# README - slf4j-reference
+
+This project gives an example of ONAP-compliant logging using SLF4J logging.
+
+## Adapter
+
+In ```org.onap.logging.ref.slf4j```, there are TWO classes:
+1. ```org.onap.logging.ref.slf4j.ONAPLogConstants```, providing declarations of standard ONAP Markers, MDCs and HTTP headers.
+2. ```org.onap.logging.ref.slf4j.ONAPLogAdapter```, providing a lightweight, compliant implementation of the ONAP logging spec.
+
+The adapter provides:
+1. A loosely-coupled SLF4j logging wrapper:
+ * To be used for logging ONAP ```entry```, ```exit``` and ```invoke``` behavior.
+ * Devolving all *application* logging to the component, via the regular SLF4J ```Logger``` facade.
+2. Customization options:
+ * *Cheap*, by way of bean properties. This is suited to most Use Cases.
+ * *Sophisticated*:
+ * By OPTIONALLY implementing one of a number of adapters:
+ * ```RequestAdapter``` to read incoming headers.
+ * ```ServiceDescriptor``` for reporting attributes of the current service.
+ * ```ResponseDescriptor``` for reporting outcomes.
+ * ```RequestBuilder``` for setting southbound request headers.
+ * By OPTIONALLY overriding methods like ```ONAPLogAdapter#setMDCs(RequestAdapter)```.
+
+Note that:
+* The adapter implementation uses static inner classes in order to fit in a single source file. This was an objective.
+
+## WAR
+
+Building produces a simple (spring-boot](https://projects.spring.io/spring-boot/) example WAR, which can be launched from this directory with:
+
+```bash
+$ java -war target/*war
+```
+
+The example WAR in ```logging-slf4j-demo``` publishes four web services:
+1. ```services/alpha```
+2. ```services/beta```
+3. ```services/gamma```
+4. ```services/delta```
+
+... each of which can invoke the others.
+
+The purpose of the WAR is to demonstrate minimalist ONAP-compliant logging for web components, but a secondary purpose is to demonstrate that the call graph can be generated for a (mostly) representative set of interacting REST services.
+
+## Tests
+
+Tests for:
+1. Code in the (potentially) reusable ``common`` package.
+2. Validating that emitted logs can be used to generate an unambiguous call graph.
diff --git a/reference/logging-slf4j/pom.xml b/reference/logging-slf4j/pom.xml
new file mode 100644
index 0000000..9cc9d4b
--- /dev/null
+++ b/reference/logging-slf4j/pom.xml
@@ -0,0 +1,91 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>org.onap.logging-analytics</groupId>
+ <artifactId>logging-reference</artifactId>
+ <version>1.2.0-SNAPSHOT</version>
+ <relativePath>..</relativePath>
+ </parent>
+ <artifactId>logging-slf4j</artifactId>
+ <name>logging-slf4j</name>
+ <packaging>jar</packaging>
+ <version>1.2.0-SNAPSHOT</version>
+
+ <dependencies>
+ <!-- Exported dependencies. -->
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-api</artifactId>
+ </dependency>
+ <!-- Provided dependencies. -->
+ <dependency>
+ <groupId>javax.servlet</groupId>
+ <artifactId>javax.servlet-api</artifactId>
+ <scope>provided</scope>
+ </dependency>
+ <!-- Test dependencies. -->
+ <dependency>
+ <groupId>ch.qos.logback</groupId>
+ <artifactId>logback-classic</artifactId>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-test</artifactId>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.testng</groupId>
+ <artifactId>testng</artifactId>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.hamcrest</groupId>
+ <artifactId>hamcrest-all</artifactId>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-api</artifactId>
+ <version>1.7.25</version>
+ </dependency>
+ <dependency>
+ <groupId>javax.servlet</groupId>
+ <artifactId>javax.servlet-api</artifactId>
+ <version>3.1.0</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>ch.qos.logback</groupId>
+ <artifactId>logback-classic</artifactId>
+ <version>1.2.3</version>
+ </dependency>
+ <dependency>
+ <groupId>org.testng</groupId>
+ <artifactId>testng</artifactId>
+ <version>6.8.5</version>
+ <exclusions>
+ <exclusion>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ <dependency>
+ <groupId>org.hamcrest</groupId>
+ <artifactId>hamcrest-all</artifactId>
+ <version>1.3</version>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-test</artifactId>
+ <version>5.0.5.RELEASE</version>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+</project>
diff --git a/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogAdapter.java b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogAdapter.java
new file mode 100644
index 0000000..50693cb
--- /dev/null
+++ b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogAdapter.java
@@ -0,0 +1,611 @@
+/**
+ * ============LICENSE_START=======================================================
+ * org.onap.logging
+ * ================================================================================
+ * Copyright © 2018 Amdocs
+ * All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.logging.ref.slf4j;
+
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+import javax.servlet.http.HttpServletRequest;
+
+import org.slf4j.Logger;
+import org.slf4j.MDC;
+import org.slf4j.Marker;
+import org.slf4j.event.Level;
+
+/**
+ * Extensible adapter for cheaply meeting ONAP logging obligations using
+ * an SLF4J facade.
+ *
+ * <p>This can be used with any SLF4J-compatible logging provider, with
+ * appropriate provider configuration.</p>
+ *
+ * <p>The basics are that:
+ * <ul>
+ * <li>{@link #entering} sets all MDCs.</li>
+ * <li>{@link #exiting} unsets all MDCs *and* logs response information.</li>
+ * <li>{@link #invoke} logs and returns a UUID to passed during invocation,
+ * and optionally sets these for you on your downstream request by way of
+ * an adapter.</li>
+ * <li>Call {@link #getServiceDescriptor()} and its setters to set service-related MDCs.</li>
+ * <li>Call {@link #getResponseDescriptor()} and its setters to set response-related MDCs.</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Minimal usage is:
+ * <ol>
+ * <li>#entering(RequestAdapter)</li>
+ * <li>#invoke, #invoke, ...</li>
+ * <li>#getResponse + setters (or #setResponse)</li>
+ * <li>#exiting</li>
+ * </ol>
+ * </p>
+ *
+ * <p> ... if you're happy for service information to be automatically derived as follows:
+ * <ul>
+ * <li><tt>ServiceName</tt> - from <tt>HttpServletRequest#getRequestURI()</tt></li>
+ * <li><tt>InstanceUUID</tt> - classloader-scope UUID.</li>
+ * </ul>
+ * </p>
+ *
+ * <p>... and if those defaults don't suit, then you can override using properties on
+ * {@link #getServiceDescriptor()}, or by injecting your own adapter using
+ * {@link #setServiceDescriptor(ServiceDescriptor)}, or by overriding
+ * a <tt>protected</tt> methods like{@link #setEnteringMDCs}.</p>
+ *
+ * <p>For everything else:
+ * <ul>
+ * <li>The underlying SLF4J {@link Logger} can be retrieved using {@link #unwrap}.
+ * Use this or create your own using the usual SLF4J factor.</li>
+ * <li>Set whatever MDCs you like.</li>
+ * <li>Log whatever else you like.</li>
+ * </ul>
+ * </p>
+ */
+public class ONAPLogAdapter {
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // Constants.
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+ /** String constant for messages <tt>ENTERING</tt>, <tt>EXITING</tt>, etc. */
+ private static final String EMPTY_MESSAGE = "";
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // Fields.
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+ /** Automatic UUID, overrideable per adapter or per invocation. */
+ private static UUID sInstanceUUID = UUID.randomUUID();
+
+ /** Logger delegate. */
+ private Logger mLogger;
+
+ /** Overrideable descriptor for the service doing the logging. */
+ private ServiceDescriptor mServiceDescriptor = new ServiceDescriptor();
+
+ /** Overrideable descriptor for the response returned by the service doing the logging. */
+ private ResponseDescriptor mResponseDescriptor = new ResponseDescriptor();
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // Constructors.
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * Construct adapter.
+ *
+ * @param logger non-null logger.
+ */
+ public ONAPLogAdapter(final Logger logger) {
+ this.mLogger = checkNotNull(logger);
+ }
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // Public methods.
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * Get logger.
+ *
+ * @return unwrapped logger.
+ */
+ public Logger unwrap() {
+ return this.mLogger;
+ }
+
+ /**
+ * Report <tt>ENTERING</tt> marker.
+ *
+ * @param request non-null incoming request (wrapper).
+ * @return this.
+ */
+ public ONAPLogAdapter entering(final RequestAdapter request) {
+
+ checkNotNull(request);
+
+ // Default the service name.
+
+ this.setEnteringMDCs(request);
+ this.mLogger.info(ONAPLogConstants.Markers.ENTRY, EMPTY_MESSAGE);
+
+ return this;
+ }
+
+ /**
+ * Report <tt>ENTERING</tt> marker.
+ *
+ * @param request non-null incoming request.
+ * @return this.
+ */
+ public ONAPLogAdapter entering(final HttpServletRequest request) {
+ return this.entering(new HttpServletRequestAdapter(checkNotNull(request)));
+ }
+
+ /**
+ * Report <tt>EXITING</tt> marker.
+ *
+ * @return this.
+ */
+ public ONAPLogAdapter exiting() {
+ try {
+ this.mResponseDescriptor.setMDCs();
+ this.mLogger.info(ONAPLogConstants.Markers.EXIT, EMPTY_MESSAGE);
+ }
+ finally {
+ MDC.clear();
+ }
+ return this;
+ }
+
+ /**
+ * Report pending invocation with <tt>INVOKE</tt> marker.
+ *
+ * <p>If you call this variant, then YOU are assuming responsibility for
+ * setting the requisite ONAP headers.</p>
+ *
+ * @param sync whether synchronous.
+ * @return invocation ID to be passed with invocation.
+ */
+ public UUID invoke(final ONAPLogConstants.InvocationMode sync) {
+
+ final UUID invocationID = UUID.randomUUID();
+
+ // Derive SYNC/ASYNC marker.
+
+ final Marker marker = (sync == null) ? ONAPLogConstants.Markers.INVOKE : sync.getMarker();
+
+ // Log INVOKE*, with the invocationID as the message body.
+ // (We didn't really want this kind of behavior in the standard,
+ // but is it worse than new, single-message MDC?)
+
+ this.mLogger.info(marker, "{}", invocationID);
+ return invocationID;
+ }
+
+ /**
+ * Report pending invocation with <tt>INVOKE</tt> marker,
+ * setting standard ONAP logging headers automatically.
+ *
+ * @param builder request builder, for setting headers.
+ * @param sync whether synchronous, nullable.
+ * @return invocation ID to be passed with invocation.
+ */
+ public UUID invoke(final RequestBuilder builder,
+ final ONAPLogConstants.InvocationMode sync) {
+
+ // Sync can be defaulted. Builder cannot.
+
+ checkNotNull(builder);
+
+ // Log INVOKE, and retain invocation ID for header + return.
+
+ final UUID invocationID = this.invoke(sync);
+
+ // Set standard HTTP headers on (southbound request) builder.
+
+ builder.setHeader(ONAPLogConstants.Headers.REQUEST_ID,
+ defaultToEmpty(MDC.get(ONAPLogConstants.MDCs.REQUEST_ID)));
+ builder.setHeader(ONAPLogConstants.Headers.INVOCATION_ID,
+ defaultToEmpty(invocationID));
+ builder.setHeader(ONAPLogConstants.Headers.PARTNER_NAME,
+ defaultToEmpty(MDC.get(ONAPLogConstants.MDCs.PARTNER_NAME)));
+
+ return invocationID;
+ }
+
+ /**
+ * Report vanilla <tt>INVOKE</tt> marker.
+ *
+ * @param builder builder for downstream requests, if you want the
+ * standard ONAP headers to be added automatically.
+ * @return invocation ID to be passed with invocation.
+ */
+ public UUID invoke(final RequestBuilder builder) {
+ return this.invoke(builder, (ONAPLogConstants.InvocationMode)null);
+ }
+
+ /**
+ * Get descriptor, for overriding service details.
+ * @return non-null descriptor.
+ */
+ public ServiceDescriptor getServiceDescriptor() {
+ return checkNotNull(this.mServiceDescriptor);
+ }
+
+ /**
+ * Override {@link ServiceDescriptor}.
+ * @param d non-null override.
+ * @return this.
+ */
+ public ONAPLogAdapter setServiceDescriptor(final ServiceDescriptor d) {
+ this.mServiceDescriptor = checkNotNull(d);
+ return this;
+ }
+
+ /**
+ * Get descriptor, for setting response details.
+ * @return non-null descriptor.
+ */
+ public ResponseDescriptor getResponseDescriptor() {
+ return checkNotNull(this.mResponseDescriptor);
+ }
+
+ /**
+ * Override {@link ResponseDescriptor}.
+ * @param d non-null override.
+ * @return this.
+ */
+ public ONAPLogAdapter setResponseDescriptor(final ResponseDescriptor d) {
+ this.mResponseDescriptor = checkNotNull(d);
+ return this;
+ }
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // Protected methods.
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * Set MDCs that persist for the duration of an invocation.
+ *
+ * <p>It would be better to roll this into {@link #entering}, like
+ * with {@link #exiting}. Then it would be easier to do, but it
+ * would mean more work. </p>
+ *
+ * @param request incoming HTTP request.
+ * @return this.
+ */
+ protected ONAPLogAdapter setEnteringMDCs(final RequestAdapter<?> request) {
+
+ // Extract MDC values from standard HTTP headers.
+
+ final String requestID = defaultToUUID(request.getHeader(ONAPLogConstants.Headers.REQUEST_ID));
+ final String invocationID = defaultToUUID(request.getHeader(ONAPLogConstants.Headers.INVOCATION_ID));
+ final String partnerName = defaultToEmpty(request.getHeader(ONAPLogConstants.Headers.PARTNER_NAME));
+
+ // Set standard MDCs. Override this entire method if you want to set
+ // others, OR set them BEFORE or AFTER the invocation of #entering,
+ // depending on where you need them to appear, OR extend the
+ // ServiceDescriptor to add them.
+
+ MDC.put(ONAPLogConstants.MDCs.INVOKE_TIMESTAMP, LocalDateTime.now().toString());
+ MDC.put(ONAPLogConstants.MDCs.REQUEST_ID, requestID);
+ MDC.put(ONAPLogConstants.MDCs.INVOCATION_ID, invocationID);
+ MDC.put(ONAPLogConstants.MDCs.PARTNER_NAME, partnerName);
+ MDC.put(ONAPLogConstants.MDCs.CLIENT_IP_ADDRESS, defaultToEmpty(request.getClientAddress()));
+ MDC.put(ONAPLogConstants.MDCs.SERVER_FQDN, defaultToEmpty(request.getServerAddress()));
+
+ // Delegate to the service adapter, for service-related DMCs.
+
+ this.mServiceDescriptor.setMDCs();
+
+ // Default the service name to the requestURI, in the event that
+ // no value has been provided.
+
+ if (MDC.get(ONAPLogConstants.MDCs.SERVICE_NAME) == null) {
+ MDC.put(ONAPLogConstants.MDCs.SERVICE_NAME, request.getRequestURI());
+ }
+
+ return this;
+ }
+
+ /**
+ * Dependency-free nullcheck.
+ *
+ * @param in to be checked.
+ * @param <T> argument (and return) type.
+ * @return input arg.
+ */
+ protected static <T> T checkNotNull(final T in) {
+ if (in == null) {
+ throw new NullPointerException();
+ }
+ return in;
+ }
+
+ /**
+ * Dependency-free string default.
+ *
+ * @param in to be filtered.
+ * @return input string or null.
+ */
+ protected static String defaultToEmpty(final Object in) {
+ if (in == null) {
+ return "";
+ }
+ return in.toString();
+ }
+
+ /**
+ * Dependency-free string default.
+ *
+ * @param in to be filtered.
+ * @return input string or null.
+ */
+ protected static String defaultToUUID(final String in) {
+ if (in == null) {
+ return UUID.randomUUID().toString();
+ }
+ return in;
+ }
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // Inner classes.
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * Extensible descriptor for reporting service details.
+ *
+ * <p>In most cases extension isn't required. </p>
+ */
+ public static class ServiceDescriptor {
+
+ /** <tt>ServiceName</tt>. */
+ protected String mName;
+
+ /** <tt>InstanceUUID</tt>. */
+ protected String mUUID = sInstanceUUID.toString();
+
+ /**
+ * Set name.
+ * @param name <tt>ServiceName</tt>.
+ * @return this.
+ */
+ public ServiceDescriptor setServiceName(final String name) {
+ this.mName = name;
+ return this;
+ }
+
+ /**
+ * Set name.
+ * @param uuid <tt>InstanceUUID</tt>.
+ * @return this.
+ */
+ public ServiceDescriptor setServiceUUID(final String uuid) {
+ this.mUUID = uuid;
+ return this;
+ }
+
+ /**
+ * Set MDCs. Once set they remain set until everything is cleared.
+ */
+ protected void setMDCs() {
+ MDC.put(ONAPLogConstants.MDCs.SERVICE_NAME, defaultToEmpty(this.mName));
+ MDC.put(ONAPLogConstants.MDCs.INSTANCE_UUID, defaultToEmpty(this.mUUID));
+ }
+ }
+
+ /**
+ * Response is different in that response MDCs are normally only
+ * reported once, for a single log message. (But there's no method
+ * for clearing them, because this is only expected to be called
+ * during <tt>#exiting</tt>.)
+ */
+ public static class ResponseDescriptor {
+
+ /** Response errorcode. */
+ protected String mCode;
+
+ /** Response description. */
+ protected String mDescription;
+
+ /** Response severity. */
+ protected Level mSeverity;
+
+ /** Response status, of {<tt>COMPLETED</tt>, <tt>ERROR</tt>}. */
+ protected ONAPLogConstants.ResponseStatus mStatus;
+
+ /**
+ * Setter.
+ *
+ * @param code response (error) code.
+ * @return this.
+ */
+ public ResponseDescriptor setResponseCode(final String code) {
+ this.mCode = code;
+ return this;
+ }
+
+ /**
+ * Setter.
+ *
+ * @param description response description.
+ * @return this.
+ */
+ public ResponseDescriptor setResponseDescription(final String description) {
+ this.mDescription = description;
+ return this;
+ }
+
+ /**
+ * Setter.
+ *
+ * @param severity response outcome severity.
+ * @return this.
+ */
+ public ResponseDescriptor setResponseSeverity(final Level severity) {
+ this.mSeverity = severity;
+ return this;
+ }
+
+ /**
+ * Setter.
+ *
+ * @param status response overall status.
+ * @return this.
+ */
+ public ResponseDescriptor setResponseStatus(final ONAPLogConstants.ResponseStatus status) {
+ this.mStatus = status;
+ return this;
+ }
+
+ /**
+ * Overrideable method to set MDCs based on property values.
+ */
+ protected void setMDCs() {
+ MDC.put(ONAPLogConstants.MDCs.RESPONSE_CODE, defaultToEmpty(this.mCode));
+ MDC.put(ONAPLogConstants.MDCs.RESPONSE_DESCRIPTION, defaultToEmpty(this.mDescription));
+ MDC.put(ONAPLogConstants.MDCs.RESPONSE_SEVERITY, defaultToEmpty(this.mSeverity));
+ MDC.put(ONAPLogConstants.MDCs.RESPONSE_STATUS_CODE, defaultToEmpty(this.mStatus));
+ }
+ }
+
+ /**
+ * Adapter for reading information from an incoming HTTP request.
+ *
+ * <p>Incoming is generally easy, because in most cases you'll be able to
+ * get your hands on the <tt>HttpServletRequest</tt>.</p>
+ *
+ * <p>Perhaps should be generalized to refer to constants instead of
+ * requiring the implementation of specific methods.</p>
+ *
+ * @param <T> type, for chaining.
+ */
+ public interface RequestAdapter<T extends RequestAdapter> {
+
+ /**
+ * Get header by name.
+ * @param name header name.
+ * @return header value, or null.
+ */
+ String getHeader(String name);
+
+ /**
+ * Get client address.
+ * @return address, if available.
+ */
+ String getClientAddress();
+
+ /**
+ * Get server address.
+ * @return address, if available.
+ */
+ String getServerAddress();
+
+ /**
+ * Get default service name, from service URI.
+ * @return service name default.
+ */
+ String getRequestURI();
+ }
+
+ /**
+ * Default {@link RequestBuilder} impl for {@link HttpServletRequest}, which
+ * will should available for most incoming REST requests.
+ */
+ public static class HttpServletRequestAdapter implements RequestAdapter<HttpServletRequestAdapter> {
+
+ /** Wrapped HTTP request. */
+ private final HttpServletRequest mRequest;
+
+ /**
+ * Construct adapter for HTTP request.
+ * @param request to be wrapped;
+ */
+ public HttpServletRequestAdapter(final HttpServletRequest request) {
+ this.mRequest = checkNotNull(request);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public String getHeader(final String name) {
+ return this.mRequest.getHeader(name);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public String getClientAddress() {
+ return this.mRequest.getRemoteAddr();
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public String getServerAddress() {
+ return this.mRequest.getServerName();
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public String getRequestURI() {
+ return this.mRequest.getRequestURI();
+ }
+ }
+
+ /**
+ * Header builder, which (unlike {@link RequestAdapter} will tend to
+ * vary a lot from caller to caller, since they each get to choose their
+ * own REST (or HTTP, or whatever) client APIs.
+ *
+ * <p>No default implementation, because there's no HTTP client that's
+ * sufficiently ubiquitous to warrant incurring a mandatory dependency.</p>
+ *
+ * @param <T> type, for chaining.
+ */
+ public interface RequestBuilder<T extends RequestBuilder> {
+
+ /**
+ * Set HTTP header.
+ * @param name header name.
+ * @param value header value.
+ * @return this.
+ */
+ T setHeader(String name, String value);
+ }
+}
diff --git a/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogConstants.java b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogConstants.java
new file mode 100644
index 0000000..744f99f
--- /dev/null
+++ b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogConstants.java
@@ -0,0 +1,253 @@
+/**
+ * ============LICENSE_START=======================================================
+ * org.onap.logging
+ * ================================================================================
+ * Copyright © 2018 Amdocs
+ * All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.logging.ref.slf4j;
+
+import org.slf4j.Marker;
+import org.slf4j.MarkerFactory;
+
+/**
+ * Constants for standard ONAP headers, MDCs, etc.
+ *
+ * <p>See <tt>package-info.java</tt>.</p>
+ */
+public final class ONAPLogConstants {
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // Constructors.
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * Hide and forbid construction.
+ */
+ private ONAPLogConstants() {
+ throw new UnsupportedOperationException();
+ }
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // Inner classes.
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * Marker constants.
+ */
+ public static final class Markers {
+
+ /** Marker reporting invocation. */
+ public static final Marker INVOKE = MarkerFactory.getMarker("INVOKE");
+
+ /** Marker reporting synchronous invocation. */
+ public static final Marker INVOKE_SYNCHRONOUS = build("INVOKE", "SYNCHRONOUS");
+
+ /** Marker reporting asynchronous invocation. */
+ public static final Marker INVOKE_ASYNCHRONOUS = build("INVOKE", "ASYNCHRONOUS");
+
+ /** Marker reporting entry into a component. */
+ public static final Marker ENTRY = MarkerFactory.getMarker("ENTRY");
+
+ /** Marker reporting exit from a component. */
+ public static final Marker EXIT = MarkerFactory.getMarker("EXIT");
+
+ /**
+ * Build nested, detached marker.
+ * @param m1 top token.
+ * @param m2 sub-token.
+ * @return detached Marker.
+ */
+ private static Marker build(final String m1, final String m2) {
+ final Marker marker = MarkerFactory.getDetachedMarker(m1);
+ marker.add(MarkerFactory.getDetachedMarker(m2));
+ return marker;
+ }
+
+ /**
+ * Hide and forbid construction.
+ */
+ private Markers() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+ /**
+ * MDC name constants.
+ */
+ public static final class MDCs {
+
+ // Tracing. ////////////////////////////////////////////////////////////
+
+ /** MDC correlating messages for an invocation. */
+ public static final String INVOCATION_ID = "InvocationID";
+
+ /** MDC correlating messages for a logical transaction. */
+ public static final String REQUEST_ID = "RequestID";
+
+ /** MDC recording calling service. */
+ public static final String PARTNER_NAME = "PartnerName";
+
+ /** MDC recording current service. */
+ public static final String SERVICE_NAME = "ServiceName";
+
+ /** MDC recording target service. */
+ public static final String TARGET_SERVICE_NAME = "TargetServiceName";
+
+ /** MDC recording current service instance. */
+ public static final String INSTANCE_UUID = "InstanceUUID";
+
+ // Network. ////////////////////////////////////////////////////////////
+
+ /** MDC recording caller address. */
+ public static final String CLIENT_IP_ADDRESS = "ClientIPAddress";
+
+ /** MDC recording server address. */
+ public static final String SERVER_FQDN = "ServerFQDN";
+
+ /**
+ * MDC recording timestamp at the start of the current request,
+ * with the same scope as {@link #REQUEST_ID}.
+ *
+ * <p>Open issues:
+ * <ul>
+ * <ul>Easily confused with {@link #INVOKE_TIMESTAMP}.</ul>
+ * <ul>No mechanism for propagation between components, e.g. via HTTP headers.</ul>
+ * <ul>Whatever mechanism we define, it's going to be costly.</ul>
+ * </ul>
+ * </p>
+ * */
+ public static final String ENTRY_TIMESTAMP = "EntryTimestamp";
+
+ /** MDC recording timestamp at the start of the current invocation. */
+ public static final String INVOKE_TIMESTAMP = "InvokeTimestamp";
+
+ // Outcomes. ///////////////////////////////////////////////////////////
+
+ /** MDC reporting outcome code. */
+ public static final String RESPONSE_CODE = "ResponseCode";
+
+ /** MDC reporting outcome description. */
+ public static final String RESPONSE_DESCRIPTION = "ResponseDescription";
+
+ /** MDC reporting outcome error level. */
+ public static final String RESPONSE_SEVERITY = "Severity";
+
+ /** MDC reporting outcome error level. */
+ public static final String RESPONSE_STATUS_CODE = "StatusCode";
+
+ // Unsorted. ///////////////////////////////////////////////////////////
+
+ /**
+ * Hide and forbid construction.
+ */
+ private MDCs() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+ /**
+ * Header name constants.
+ */
+ public static final class Headers {
+
+ /** HTTP <tt>X-ONAP-RequestID</tt> header. */
+ public static final String REQUEST_ID = "X-ONAP-RequestID";
+
+ /** HTTP <tt>X-ONAP-InvocationID</tt> header. */
+ public static final String INVOCATION_ID = "X-ONAP-InvocationID";
+
+ /** HTTP <tt>X-ONAP-PartnerName</tt> header. */
+ public static final String PARTNER_NAME = "X-ONAP-PartnerName";
+
+ /**
+ * Hide and forbid construction.
+ */
+ private Headers() {
+ throw new UnsupportedOperationException();
+ }
+ }
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //
+ // Enums.
+ //
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * Response success or not, for setting <tt>StatusCode</tt>.
+ */
+ public enum ResponseStatus {
+
+ /** Success. */
+ COMPLETED,
+
+ /** Not. */
+ ERROR,
+ }
+
+ /**
+ * Synchronous or asynchronous execution, for setting invocation marker.
+ */
+ public enum InvocationMode {
+
+ /** Synchronous, blocking. */
+ SYNCHRONOUS("SYNCHRONOUS", Markers.INVOKE_SYNCHRONOUS),
+
+ /** Asynchronous, non-blocking. */
+ ASYNCHRONOUS("ASYNCHRONOUS", Markers.INVOKE_ASYNCHRONOUS);
+
+ /** Enum value. */
+ private String mString;
+
+ /** Corresponding marker. */
+ private Marker mMarker;
+
+ /**
+ * Construct enum.
+ *
+ * @param s enum value.
+ * @param m corresponding Marker.
+ */
+ InvocationMode(final String s, final Marker m) {
+ this.mString = s;
+ this.mMarker = m;
+ }
+
+ /**
+ * Get Marker for enum.
+ *
+ * @return Marker.
+ */
+ public Marker getMarker() {
+ return this.mMarker;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public String toString() {
+ return this.mString;
+ }
+ }
+
+}
diff --git a/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/package-info.java b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/package-info.java
new file mode 100644
index 0000000..d9a6247
--- /dev/null
+++ b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/package-info.java
@@ -0,0 +1,32 @@
+/**
+ * ============LICENSE_START=======================================================
+ * org.onap.logging
+ * ================================================================================
+ * Copyright © 2018 Amdocs
+ * All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.logging.ref.slf4j;
+
+/**
+ * <p>Code in here has potential application outside this reference
+ * example, and accordingly:
+ * <ul>
+ * <li>Packaged in <tt>common</tt>.</li>
+ * <li>Has minimal dependencies.</li>
+ * </ul>
+ * </p>
+ */ \ No newline at end of file
diff --git a/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterOutputTest.java b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterOutputTest.java
new file mode 100644
index 0000000..bab74bb
--- /dev/null
+++ b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterOutputTest.java
@@ -0,0 +1,162 @@
+/**
+ * ============LICENSE_START=======================================================
+ * org.onap.logging
+ * ================================================================================
+ * Copyright © 2018 Amdocs
+ * All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.logging.ref.slf4j;
+
+import java.io.BufferedReader;
+import java.io.File;
+import java.io.FileReader;
+import java.nio.file.Files;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+import javax.xml.bind.DatatypeConverter;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.slf4j.MDC;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.testng.annotations.AfterSuite;
+import org.testng.annotations.BeforeSuite;
+import org.testng.annotations.Test;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.core.Is.is;
+import static org.hamcrest.core.IsNot.not;
+import static org.hamcrest.core.IsNull.notNullValue;
+import static org.hamcrest.core.StringContains.containsString;
+import static org.hamcrest.number.OrderingComparison.greaterThan;
+
+/**
+ * Smoketest output, though the embedded configuration isn't necessarily
+ * canonical.
+ *
+ * <p>There are more comprehensive tests in the <tt>logging-slf4j-demo</tt>
+ * project.</p>
+ */
+public class ONAPLogAdapterOutputTest {
+
+ /** Temporary directory into which logfiles are written. */
+ private static File sDir;
+
+ @BeforeSuite
+ public static void setUp() throws Exception {
+ sDir = Files.createTempDirectory(ONAPLogAdapterOutputTest.class.getName()).toFile();
+ System.getProperties().setProperty("SLF4J_OUTPUT_DIRECTORY", sDir.getAbsolutePath());
+ LoggerFactory.getLogger(ONAPLogAdapterOutputTest.class).info("Starting.");
+ }
+
+ @AfterSuite
+ public static void tearDown() throws Exception {
+ LoggerFactory.getLogger(ONAPLogAdapterOutputTest.class).info("Ending.");
+ Thread.sleep(1000L);
+ if (sDir != null) {
+ System.err.println("Should be deleting [" + sDir.getAbsolutePath() + "]...");
+ }
+ }
+
+ @Test
+ public void testOutput() throws Exception {
+
+ assertThat(sDir, notNullValue());
+ assertThat(sDir.isDirectory(), is(true));
+
+ final String uuid = UUID.randomUUID().toString();
+ final String errorcode = UUID.randomUUID().toString();
+ final Logger logger = LoggerFactory.getLogger(ONAPLogAdapterOutputTest.class);
+
+ try {
+ MDC.put("uuid", uuid);
+ final ONAPLogAdapter adapter = new ONAPLogAdapter(logger);
+ final ONAPLogAdapter.HttpServletRequestAdapter http
+ = new ONAPLogAdapter.HttpServletRequestAdapter(new MockHttpServletRequest());
+ adapter.entering(http);
+ adapter.unwrap().warn("a_warning");
+ try {
+ throw new Exception("errorcode=" + errorcode);
+ }
+ catch (final Exception e) {
+ adapter.unwrap().error("an_error", e);
+ }
+
+ Thread.sleep(1000L);
+ }
+ finally {
+ MDC.clear();
+ }
+
+ final List<String> lines = new ArrayList<>();
+ for (final File f : sDir.listFiles()) {
+ try (BufferedReader reader = new BufferedReader(new FileReader(f))) {
+ String line;
+ while ((line = reader.readLine()) != null) {
+ if (line.contains(uuid)) {
+ lines.add(line);
+ }
+ }
+ }
+ }
+
+ assertThat(lines.size(), is(3));
+
+ assertThat(lines.get(0), containsString("ENTRY"));
+ final String [] line0 = lines.get(0).split("\t", -1);
+ assertThat(line0.length, is(9));
+ DatatypeConverter.parseDateTime(line0[0]);
+ assertThat(line0[1].trim().length(), greaterThan(1));
+ assertThat(line0[2], is("INFO"));
+ assertThat(line0[3], is(this.getClass().getName()));
+ assertThat(line0[4], containsString("uuid=" + uuid));
+ assertThat(line0[5], is(""));
+ assertThat(line0[6], is(""));
+ assertThat(line0[7], is("ENTRY"));
+ System.err.println(lines.get(0));
+
+ assertThat(lines.get(1), not(containsString("ENTRY")));
+ assertThat(lines.get(1), containsString("a_warning"));
+ final String [] line1 = lines.get(1).split("\t", -1);
+ assertThat(line1.length, is(9));
+ DatatypeConverter.parseDateTime(line1[0]);
+ assertThat(line1[1].trim().length(), greaterThan(1));
+ assertThat(line1[2], is("WARN"));
+ assertThat(line1[3], is(this.getClass().getName()));
+ assertThat(line1[4], containsString("uuid=" + uuid));
+ assertThat(line1[5], is("a_warning"));
+ assertThat(line1[6], is(""));
+ assertThat(line1[7], is(""));
+ System.err.println(lines.get(1));
+
+ assertThat(lines.get(2), not(containsString("ENTRY")));
+ assertThat(lines.get(2), containsString("an_error"));
+ final String [] line2 = lines.get(2).split("\t", -1);
+ assertThat(line2.length, is(9));
+ DatatypeConverter.parseDateTime(line2[0]);
+ assertThat(line2[1].trim().length(), greaterThan(1));
+ assertThat(line2[2], is("ERROR"));
+ assertThat(line2[3], is(this.getClass().getName()));
+ assertThat(line2[4], containsString("uuid=" + uuid));
+ assertThat(line2[5], is("an_error"));
+ assertThat(line2[6], containsString("errorcode=" + errorcode));
+ assertThat(line2[7], is(""));
+ System.err.println(lines.get(2));
+ }
+}
diff --git a/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterTest.java b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterTest.java
new file mode 100644
index 0000000..ad22603
--- /dev/null
+++ b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterTest.java
@@ -0,0 +1,387 @@
+/**
+ * ============LICENSE_START=======================================================
+ * org.onap.logging
+ * ================================================================================
+ * Copyright © 2018 Amdocs
+ * All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.logging.ref.slf4j;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.UUID;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.slf4j.MDC;
+import org.slf4j.event.Level;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.testng.Assert;
+import org.testng.annotations.AfterMethod;
+import org.testng.annotations.Test;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.core.Is.is;
+import static org.hamcrest.core.IsNot.not;
+import static org.hamcrest.core.IsNull.notNullValue;
+import static org.hamcrest.core.IsNull.nullValue;
+import static org.hamcrest.core.IsSame.sameInstance;
+
+/**
+ * Tests for {@link ONAPLogAdapter}.
+ */
+public class ONAPLogAdapterTest {
+
+ /**
+ * Ensure that MDCs are cleared after each testcase.
+ */
+ @AfterMethod
+ public void resetMDCs() {
+ MDC.clear();
+ }
+
+ /**
+ * Test nullcheck.
+ */
+ @Test
+ public void testCheckNotNull() {
+
+ ONAPLogAdapter.checkNotNull("");
+
+ try {
+ ONAPLogAdapter.checkNotNull(null);
+ Assert.fail("Should throw NullPointerException");
+ }
+ catch (final NullPointerException e) {
+
+ }
+ }
+
+ /**
+ * Test defaulting of nulls.
+ */
+ @Test
+ public void testDefaultToEmpty() {
+ assertThat(ONAPLogAdapter.defaultToEmpty("123"), is("123"));
+ assertThat(ONAPLogAdapter.defaultToEmpty(Integer.valueOf(1984)), is("1984"));
+ assertThat(ONAPLogAdapter.defaultToEmpty(null), is(""));
+ }
+
+ /**
+ * Test defaulting of nulls.
+ */
+ @Test
+ public void testDefaultToUUID() {
+ assertThat(ONAPLogAdapter.defaultToUUID("123"), is("123"));
+ UUID.fromString(ONAPLogAdapter.defaultToUUID(null));
+ }
+
+ /**
+ * Test ENTERING.
+ */
+ @Test
+ public void testEntering() {
+
+ final Logger logger = LoggerFactory.getLogger(this.getClass());
+ final ONAPLogAdapter adapter = new ONAPLogAdapter(logger);
+ final MockHttpServletRequest http = new MockHttpServletRequest();
+ http.setRequestURI("uri123");
+ http.setServerName("local123");
+ http.setRemoteAddr("remote123");
+ http.addHeader("X-ONAP-RequestID", "request123");
+ http.addHeader("X-ONAP-InvocationID", "invocation123");
+ http.addHeader("X-ONAP-PartnerName", "partner123");
+
+ try {
+ adapter.getServiceDescriptor().setServiceName("uri123");
+ adapter.entering(http);
+ final Map<String, String> mdcs = MDC.getCopyOfContextMap();
+ assertThat(mdcs.get("RequestID"), is("request123"));
+ assertThat(mdcs.get("InvocationID"), is("invocation123"));
+ assertThat(mdcs.get("PartnerName"), is("partner123"));
+ assertThat(mdcs.get("ServiceName"), is("uri123"));
+ assertThat(mdcs.get("ServerFQDN"), is("local123"));
+ assertThat(mdcs.get("ClientIPAddress"), is("remote123"));
+ }
+ finally {
+ MDC.clear();
+ }
+ }
+
+ @Test
+ public void testSetServiceDescriptor() {
+ final ONAPLogAdapter.ServiceDescriptor override = new ONAPLogAdapter.ServiceDescriptor();
+ final Logger logger = LoggerFactory.getLogger(this.getClass());
+ final ONAPLogAdapter adapter = new ONAPLogAdapter(logger);
+ final ONAPLogAdapter.ServiceDescriptor before = adapter.getServiceDescriptor();
+ adapter.setServiceDescriptor(override);
+ final ONAPLogAdapter.ServiceDescriptor after = adapter.getServiceDescriptor();
+ assertThat(after, not(sameInstance(before)));
+ assertThat(after, is(override));
+ }
+
+ @Test
+ public void testSetResponseDescriptor() {
+ final ONAPLogAdapter.ResponseDescriptor override = new ONAPLogAdapter.ResponseDescriptor();
+ final Logger logger = LoggerFactory.getLogger(this.getClass());
+ final ONAPLogAdapter adapter = new ONAPLogAdapter(logger);
+ final ONAPLogAdapter.ResponseDescriptor before = adapter.getResponseDescriptor();
+ adapter.setResponseDescriptor(override);
+ final ONAPLogAdapter.ResponseDescriptor after = adapter.getResponseDescriptor();
+ assertThat(after, not(sameInstance(before)));
+ assertThat(after, is(override));
+ }
+
+ @Test
+ public void testUnwrap() {
+ final Logger logger = LoggerFactory.getLogger(this.getClass());
+ final ONAPLogAdapter adapter = new ONAPLogAdapter(logger);
+ assertThat(adapter.unwrap(), is(logger));
+ }
+
+ /**
+ * Test EXITING.
+ */
+ @Test
+ public void testExiting() {
+
+ final Logger logger = LoggerFactory.getLogger(this.getClass());
+ final ONAPLogAdapter adapter = new ONAPLogAdapter(logger);
+
+ try {
+ MDC.put("somekey", "somevalue");
+ assertThat(MDC.get("somekey"), is("somevalue"));
+ adapter.exiting();
+ assertThat(MDC.get("somekey"), nullValue());
+ }
+ finally {
+ MDC.clear();
+ }
+ }
+
+ /**
+ * Test INVOKE.
+ */
+ @Test
+ public void testInvokeSyncAsyncNull() {
+
+ final Logger logger = LoggerFactory.getLogger(this.getClass());
+ final ONAPLogAdapter adapter = new ONAPLogAdapter(logger);
+
+ final UUID syncUUID = adapter.invoke(ONAPLogConstants.InvocationMode.SYNCHRONOUS);
+ assertThat(syncUUID, notNullValue());
+
+ final UUID asyncUUID = adapter.invoke(ONAPLogConstants.InvocationMode.SYNCHRONOUS);
+ assertThat(asyncUUID, notNullValue());
+
+ final UUID agnosticUUID = adapter.invoke((ONAPLogConstants.InvocationMode)null);
+ assertThat(agnosticUUID, notNullValue());
+
+ }
+
+ /**
+ * Test INVOKE, with RequestAdapter.
+ */
+ @Test
+ public void testInvokeWithAdapter() throws Exception {
+
+ final Logger logger = LoggerFactory.getLogger(this.getClass());
+ final ONAPLogAdapter adapter = new ONAPLogAdapter(logger);
+
+ final Map<String, String> headers = new HashMap<>();
+ final ONAPLogAdapter.RequestBuilder builder = new ONAPLogAdapter.RequestBuilder<ONAPLogAdapter.RequestBuilder>() {
+ @Override
+ public ONAPLogAdapter.RequestBuilder setHeader(final String name, final String value) {
+ headers.put(name, value);
+ return this;
+ }
+ };
+
+ try {
+ final UUID uuid = adapter.invoke(builder, ONAPLogConstants.InvocationMode.SYNCHRONOUS);
+ assertThat(uuid, notNullValue());
+ assertThat(headers.get(ONAPLogConstants.Headers.INVOCATION_ID), is(uuid.toString()));
+ assertThat(headers.containsKey(ONAPLogConstants.Headers.PARTNER_NAME), is(true));
+ assertThat(headers.containsKey(ONAPLogConstants.Headers.REQUEST_ID), is(true));
+ }
+ finally {
+ MDC.clear();
+ }
+ }
+
+ /**
+ * Test INVOKE, with RequestAdapter.
+ */
+ @Test
+ public void testInvokeWithAdapterAndNull() throws Exception {
+
+ final Logger logger = LoggerFactory.getLogger(this.getClass());
+ final ONAPLogAdapter adapter = new ONAPLogAdapter(logger);
+
+ final Map<String, String> headers = new HashMap<>();
+ final ONAPLogAdapter.RequestBuilder builder = new ONAPLogAdapter.RequestBuilder<ONAPLogAdapter.RequestBuilder>() {
+ @Override
+ public ONAPLogAdapter.RequestBuilder setHeader(final String name, final String value) {
+ headers.put(name, value);
+ return this;
+ }
+ };
+
+ try {
+ final UUID uuid = adapter.invoke(builder);
+ assertThat(uuid, notNullValue());
+ assertThat(headers.get(ONAPLogConstants.Headers.INVOCATION_ID), is(uuid.toString()));
+ assertThat(headers.containsKey(ONAPLogConstants.Headers.PARTNER_NAME), is(true));
+ assertThat(headers.containsKey(ONAPLogConstants.Headers.REQUEST_ID), is(true));
+ }
+ finally {
+ MDC.clear();
+ }
+ }
+
+ @Test
+ public void testHttpServletRequestAdapter() {
+
+ final UUID uuid = UUID.randomUUID();
+ final MockHttpServletRequest request = new MockHttpServletRequest();
+ request.addHeader("uuid", uuid.toString());
+ request.setRequestURI("/ctx0");
+ request.setServerName("srv0");
+
+ final ONAPLogAdapter.HttpServletRequestAdapter adapter
+ = new ONAPLogAdapter.HttpServletRequestAdapter(request);
+ assertThat(adapter.getHeader("uuid"), is(uuid.toString()));
+ assertThat(adapter.getRequestURI(), is("/ctx0"));
+ assertThat(adapter.getServerAddress(), is("srv0"));
+ }
+
+ @Test
+ public void testServiceDescriptor() {
+ final String uuid = UUID.randomUUID().toString();
+
+ final ONAPLogAdapter.ServiceDescriptor adapter
+ = new ONAPLogAdapter.ServiceDescriptor();
+ adapter.setServiceUUID(uuid);
+ adapter.setServiceName("name0");
+
+ assertThat(MDC.get(ONAPLogConstants.MDCs.SERVICE_NAME), nullValue());
+ assertThat(MDC.get(ONAPLogConstants.MDCs.INSTANCE_UUID), nullValue());
+
+ adapter.setMDCs();
+
+ assertThat(MDC.get(ONAPLogConstants.MDCs.SERVICE_NAME), is("name0"));
+ assertThat(MDC.get(ONAPLogConstants.MDCs.INSTANCE_UUID), is(uuid));
+ }
+
+ @Test
+ public void testResponseDescriptor() {
+ final String uuid = UUID.randomUUID().toString();
+
+ final ONAPLogAdapter.ResponseDescriptor adapter
+ = new ONAPLogAdapter.ResponseDescriptor();
+ adapter.setResponseCode("code0");
+ adapter.setResponseDescription("desc0");
+ adapter.setResponseSeverity(Level.INFO);
+ adapter.setResponseStatus(ONAPLogConstants.ResponseStatus.COMPLETED);
+
+ assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_CODE), nullValue());
+ assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_DESCRIPTION), nullValue());
+ assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_SEVERITY), nullValue());
+ assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_STATUS_CODE), nullValue());
+
+ adapter.setMDCs();
+
+ assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_CODE), is("code0"));
+ assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_DESCRIPTION), is("desc0"));
+ assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_SEVERITY), is("INFO"));
+ assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_STATUS_CODE), is("COMPLETED"));
+ }
+
+ /**
+ * Exercise the contract, for a caller that's happy to have their
+ * service name automatically derived. (This validates nothing
+ * and achieves nothing; it's just to provide an example of minimal usage).
+ */
+ @Test
+ public void testContract() {
+
+ // Note no wrapper around HttpServletRequest, which will work for
+ // most invocations (since they come via HTTP), but otherwise
+ // can implement your own RequestAdapter.
+
+ final Logger logger = LoggerFactory.getLogger(this.getClass());
+ final ONAPLogAdapter adapter = new ONAPLogAdapter(logger);
+ final MockHttpServletRequest http = new MockHttpServletRequest();
+
+ // Immediately log ENTERING marker, with global MDCs.
+
+ adapter.entering(http);
+ try {
+
+ // Generate (and log) an invocationID, then use it to
+ // invoke another component.
+
+ final RESTClient client = new RESTClient(); // implements ONAPLogAdapter.RequestBuilder<RESTClient>.
+ adapter.invoke(client, ONAPLogConstants.InvocationMode.SYNCHRONOUS);
+ final RESTRequest request = null; // TODO: build real request.
+ final RESTResponse response = client.execute(request); // TODO: handle real response.
+
+ // Set response details prior to #exiting.
+ // (Obviously there'd be errorhandling, etc. IRL).
+
+ adapter.getResponseDescriptor()
+ .setResponseCode((String)null)
+ .setResponseSeverity(Level.INFO)
+ .setResponseStatus(ONAPLogConstants.ResponseStatus.COMPLETED);
+ }
+ finally {
+
+ // Return, logging EXIT marker, with response MDCs.
+
+ adapter.exiting();
+ }
+ }
+
+ /**
+ * Dummy class, for example code.
+ */
+ static class RESTClient implements ONAPLogAdapter.RequestBuilder<RESTClient> {
+
+ @Override
+ public RESTClient setHeader(final String name, final String value) {
+ return null;
+ }
+
+ RESTResponse execute(RESTRequest request) {
+ return null;
+ }
+ }
+
+ /**
+ * Dummy class, for example code.
+ */
+ static class RESTRequest {
+
+ }
+
+ /**
+ * Dummy class, for example code.
+ */
+ static class RESTResponse {
+
+ }
+}
diff --git a/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogConstantsTest.java b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogConstantsTest.java
new file mode 100644
index 0000000..f6642f9
--- /dev/null
+++ b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogConstantsTest.java
@@ -0,0 +1,133 @@
+/**
+ * ============LICENSE_START=======================================================
+ * org.onap.logging
+ * ================================================================================
+ * Copyright © 2018 Amdocs
+ * All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.logging.ref.slf4j;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationTargetException;
+
+import org.testng.Assert;
+import org.testng.annotations.Test;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.core.Is.is;
+import static org.hamcrest.core.IsInstanceOf.instanceOf;
+
+/**
+ * Tests for {@link ONAPLogConstants}.
+ */
+public class ONAPLogConstantsTest {
+
+ @Test
+ public void testConstructors() throws Exception {
+ assertInaccessibleConstructor(ONAPLogConstants.class);
+ assertInaccessibleConstructor(ONAPLogConstants.MDCs.class);
+ assertInaccessibleConstructor(ONAPLogConstants.Markers.class);
+ assertInaccessibleConstructor(ONAPLogConstants.Headers.class);
+ }
+
+ @Test
+ public void testConstructorUnsupported() throws Exception {
+ try {
+ Constructor<?> c = ONAPLogConstants.class.getDeclaredConstructors()[0];
+ c.setAccessible(true);
+ c.newInstance();
+ Assert.fail("Should fail for hidden constructor.");
+ }
+ catch (final InvocationTargetException e) {
+ assertThat(e.getCause(), instanceOf(UnsupportedOperationException.class));
+ }
+ }
+
+ @Test
+ public void testHeaders() {
+ assertThat(ONAPLogConstants.Headers.REQUEST_ID, is("X-ONAP-RequestID"));
+ assertThat(ONAPLogConstants.Headers.INVOCATION_ID, is("X-ONAP-InvocationID"));
+ assertThat(ONAPLogConstants.Headers.PARTNER_NAME, is("X-ONAP-PartnerName"));
+ }
+
+ @Test
+ public void testMarkers() {
+ assertThat(ONAPLogConstants.Markers.ENTRY.toString(), is("ENTRY"));
+ assertThat(ONAPLogConstants.Markers.EXIT.toString(), is("EXIT"));
+ assertThat(ONAPLogConstants.Markers.INVOKE.toString(), is("INVOKE"));
+ assertThat(ONAPLogConstants.Markers.INVOKE_ASYNCHRONOUS.toString(), is("INVOKE [ ASYNCHRONOUS ]"));
+ assertThat(ONAPLogConstants.Markers.INVOKE_SYNCHRONOUS.toString(), is("INVOKE [ SYNCHRONOUS ]"));
+ }
+
+ @Test
+ public void testInvocationMode() {
+ assertThat(ONAPLogConstants.InvocationMode.SYNCHRONOUS.getMarker(),
+ is(ONAPLogConstants.Markers.INVOKE_SYNCHRONOUS));
+ assertThat(ONAPLogConstants.InvocationMode.ASYNCHRONOUS.getMarker(),
+ is(ONAPLogConstants.Markers.INVOKE_ASYNCHRONOUS));
+ }
+
+ @Test
+ public void testInvocationModeToString() {
+ assertThat(ONAPLogConstants.InvocationMode.SYNCHRONOUS.toString(),
+ is("SYNCHRONOUS"));
+ }
+
+ @Test
+ public void testResponseStatus() {
+ assertThat(ONAPLogConstants.ResponseStatus.COMPLETED.toString(), is("COMPLETED"));
+ assertThat(ONAPLogConstants.ResponseStatus.ERROR.toString(), is("ERROR"));
+ }
+
+ @Test
+ public void testMDCs() {
+
+ assertThat(ONAPLogConstants.MDCs.CLIENT_IP_ADDRESS.toString(), is("ClientIPAddress"));
+ assertThat(ONAPLogConstants.MDCs.SERVER_FQDN.toString(), is("ServerFQDN"));
+
+ assertThat(ONAPLogConstants.MDCs.ENTRY_TIMESTAMP.toString(), is("EntryTimestamp"));
+ assertThat(ONAPLogConstants.MDCs.INVOKE_TIMESTAMP.toString(), is("InvokeTimestamp"));
+
+ assertThat(ONAPLogConstants.MDCs.REQUEST_ID.toString(), is("RequestID"));
+ assertThat(ONAPLogConstants.MDCs.INVOCATION_ID.toString(), is("InvocationID"));
+ assertThat(ONAPLogConstants.MDCs.PARTNER_NAME.toString(), is("PartnerName"));
+ assertThat(ONAPLogConstants.MDCs.INSTANCE_UUID.toString(), is("InstanceUUID"));
+ assertThat(ONAPLogConstants.MDCs.SERVICE_NAME.toString(), is("ServiceName"));
+ assertThat(ONAPLogConstants.MDCs.TARGET_SERVICE_NAME.toString(), is("TargetServiceName"));
+
+ }
+
+ static void assertInaccessibleConstructor(final Class<?> c) throws Exception {
+ try {
+ c.getDeclaredConstructors()[0].newInstance();
+ Assert.fail("Should fail for hidden constructor.");
+ }
+ catch (final IllegalAccessException e) {
+
+ }
+
+ try {
+ final Constructor<?> constructor = c.getDeclaredConstructors()[0];
+ constructor.setAccessible(true);
+ constructor.newInstance();
+ Assert.fail("Should fail even when invoked.");
+ }
+ catch (final InvocationTargetException e) {
+ assertThat(e.getCause(), instanceOf(UnsupportedOperationException.class));
+ }
+ }
+}
diff --git a/reference/logging-slf4j/src/test/java/testng.xml b/reference/logging-slf4j/src/test/java/testng.xml
new file mode 100644
index 0000000..7b31c26
--- /dev/null
+++ b/reference/logging-slf4j/src/test/java/testng.xml
@@ -0,0 +1,8 @@
+<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd">
+<suite name="org.onap.logging.ref.slf4j" verbose="9" thread-count="1" parallel="methods">
+ <test name="all" thread-count="1" enabled="true">
+ <packages>
+ <package name="org.onap.logging.ref.slf4j.*"/>
+ </packages>
+ </test>
+</suite> \ No newline at end of file
diff --git a/reference/logging-slf4j/src/test/resources/logback.xml b/reference/logging-slf4j/src/test/resources/logback.xml
new file mode 100644
index 0000000..554d712
--- /dev/null
+++ b/reference/logging-slf4j/src/test/resources/logback.xml
@@ -0,0 +1,35 @@
+<configuration>
+
+ <property name="p_tim" value="%d{&quot;yyyy-MM-dd'T'HH:mm:ss.SSSXXX&quot;, UTC}"/>
+ <property name="p_lvl" value="%level"/>
+ <property name="p_log" value="%logger"/>
+ <property name="p_mdc" value="%replace(%replace(%mdc){'\t','\\\\t'}){'\n', '\\\\n'}"/>
+ <property name="p_msg" value="%replace(%replace(%msg){'\t', '\\\\t'}){'\n','\\\\n'}"/>
+ <property name="p_exc" value="%replace(%replace(%rootException){'\t', '\\\\t'}){'\n','\\\\n'}"/>
+ <property name="p_mak" value="%replace(%replace(%marker){'\t', '\\\\t'}){'\n','\\\\n'}"/>
+ <property name="p_thr" value="%thread"/>
+ <property name="pattern" value="%nopexception${p_tim}\t${p_thr}\t${p_lvl}\t${p_log}\t${p_mdc}\t${p_msg}\t${p_exc}\t${p_mak}\t%n"/>
+
+ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+ <encoder>
+ <pattern>${pattern}</pattern>
+ </encoder>
+ </appender>
+
+ <appender name="FILE" class="ch.qos.logback.core.FileAppender">
+ <file>${SLF4J_OUTPUT_DIRECTORY}/output.log</file>
+ <encoder>
+ <pattern>${pattern}</pattern>
+ </encoder>
+ </appender>
+
+ <logger level="debug" name="org.onap.logging.ref.slf4j" additivity="false">
+ <appender-ref ref="STDOUT" />
+ <appender-ref ref="FILE" />
+ </logger>
+
+ <root level="error">
+ <appender-ref ref="STDOUT" />
+ </root>
+
+</configuration>