DockerEventListener extension point, which is being used to notify listeners about new records.
+The plugin provides the DockerEventListener extension point, which is being used to notify listeners about new records.
Docker Traceability functionality also listens to these endpoints, so it is possible to notify the plugin about new records using DockerEventListener#fire() method.
@@ -80,24 +80,23 @@ For each container record the plugin publishes the info on the container summary
-
If an external client submits information about the image (which can be retrieved using *docker inspect imageId* command), the plugin captures this image and adds a new facet to the image fingerprint page.
-Raw data is accessible via the [plugin's API](#API) or via hyperlinks on info pages.
+Raw data is accessible via the [plugin's API](#api) or via hyperlinks on info pages.
## Search
-You can search deployments by container IDs using the "Search" control on the "Docker Traceability" page. You can also query containers using the [plugin's API](#API).
+You can search deployments by container IDs using the "Search" control on the "Docker Traceability" page. You can also query containers using the [plugin's API](#api).
-#Integrations
+# Integrations
-CloudBees Docker Traceability plugin is based on fingerprints provided by [Docker Commons Plugin][docker-commons]. The plugin just adds additional facets to main fingerprint pages, so any other plugin can contribute to the UI by adding additional facets to the fingerprint.
+CloudBees Docker Traceability plugin is based on fingerprints provided by [Docker Commons Plugin][docker-commons]. The plugin just adds additional facets to main fingerprint pages, so any other plugin can contribute to the UI by adding additional facets to the fingerprint.
See [Docker Commons Plugin Wiki page][docker-commons] to get an info about existing fingerprint contributors.
-#API
+# API
The detailed description of API endpoints is available in the "api" page of the "Docker Traceability" root action (see *$(JENKINS_URL)/docker-traceability/api*)
diff --git a/docker-java-shaded/.gitignore b/docker-java-shaded/.gitignore
index 2e73990..916e17c 100644
--- a/docker-java-shaded/.gitignore
+++ b/docker-java-shaded/.gitignore
@@ -1 +1 @@
-dependency-reduced-pom.xml
\ No newline at end of file
+dependency-reduced-pom.xml
diff --git a/docker-traceability-plugin/src/main/java/org/jenkinsci/plugins/docker/traceability/core/DockerTraceabilityRootAction.java b/docker-traceability-plugin/src/main/java/org/jenkinsci/plugins/docker/traceability/core/DockerTraceabilityRootAction.java
index 32427db..5ddc9cb 100644
--- a/docker-traceability-plugin/src/main/java/org/jenkinsci/plugins/docker/traceability/core/DockerTraceabilityRootAction.java
+++ b/docker-traceability-plugin/src/main/java/org/jenkinsci/plugins/docker/traceability/core/DockerTraceabilityRootAction.java
@@ -24,6 +24,7 @@
package org.jenkinsci.plugins.docker.traceability.core;
import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
import hudson.BulkChange;
import hudson.Extension;
import hudson.XmlFile;
@@ -341,16 +342,16 @@ public void doImage(StaplerRequest req, StaplerResponse rsp,
//TODO: filtering by container ID, imageID, containerName, imageName, hostName, hostID, environment
/**
* Retrieves the latest container status via API.
- * The output will be retrieved in JSON. Supports filers. Missing
- * "since" and "until"
+ * Supports filers. Missing "since" and "until"
* @param id ID of the container, for which the info should be retrieved.
* Short container IDs are not supported.
+ * @param format Format used in the response. See {@link ResponseFormat} for supported format.
* @throws IOException Processing error
* @throws ServletException Servlet error
- * @return Raw JSON output compatible with docker inspect
+ * @return Response available in different formats, including a JSON output compatible with docker inspect
*/
- public HttpResponse doRawContainerInfo(@QueryParameter(required = true) String id)
- throws IOException, ServletException {
+ public HttpResponse doRawContainerInfo(@QueryParameter(required = true) String id, @QueryParameter(required = false) final String format)
+ throws IOException, ServletException {
checkPermission(DockerTraceabilityPlugin.READ_DETAILS);
//TODO: check containerID format
@@ -364,9 +365,8 @@ public HttpResponse doRawContainerInfo(@QueryParameter(required = true) String i
return HttpResponses.error(500, "Cannot retrieve the container's status");
}
- // Return raw JSON in the response
InspectContainerResponse[] out = {inspectInfo};
- return toJSONResponse(out);
+ return toFormattedResponse(out, format);
}
//TODO: More filtering
@@ -380,15 +380,17 @@ public HttpResponse doRawContainerInfo(@QueryParameter(required = true) String i
* If the value equals to 0, the filter will be ignored (default in {@link QueryParameter}).
* @param until End time.
* If the value equals to 0, the filter will be ignored (default in {@link QueryParameter}).
+ * @param format Format used in the response. See {@link ResponseFormat} for supported format.
* @throws IOException Processing error
* @throws ServletException Servlet error
- * @return Response containing the output JSON. may be an error if something breaks.
+ * @return Response available in different formats. may be an error if something breaks.
*/
public HttpResponse doQueryContainer(
@QueryParameter(required = true) String id,
@QueryParameter(required = false) String mode,
@QueryParameter(required = false) long since,
- @QueryParameter(required = false) long until)
+ @QueryParameter(required = false) long until,
+ @QueryParameter(required = false) String format)
throws IOException, ServletException {
checkPermission(DockerTraceabilityPlugin.READ_DETAILS);
@@ -439,21 +441,23 @@ public HttpResponse doQueryContainer(
}
}
- // Return raw JSON in the response
- return toJSONResponse(result);
+ return toFormattedResponse(result, format);
}
/**
* Retrieves the latest raw status via API.
- * The output will be retrieved in JSON.
+ *
* @param id ID of the image, for which the info should be retrieved.
* Short container IDs are not supported.
+ * @param format Format used in the output response. See {@link ResponseFormat} for supported format.
+ *
* @throws IOException Processing error
* @throws ServletException Servlet error
- * @return {@link HttpResponse}
+ *
+ * @return Response ({@link HttpResponse}) available in different formats
*/
- public HttpResponse doRawImageInfo(@QueryParameter(required = true) String id)
- throws IOException, ServletException {
+ public HttpResponse doRawImageInfo(@QueryParameter(required = true) String id, @QueryParameter(required = false) String format)
+ throws IOException, ServletException {
checkPermission(DockerTraceabilityPlugin.READ_DETAILS);
final InspectImageResponse report = DockerTraceabilityHelper.getLastInspectImageResponse(id);
@@ -461,9 +465,8 @@ public HttpResponse doRawImageInfo(@QueryParameter(required = true) String id)
return HttpResponses.error(404, "No info available for the imageId=" + id);
}
- // Return raw JSON in the response
InspectImageResponse[] out = {report};
- return toJSONResponse(out);
+ return toFormattedResponse(out, format);
}
/**
@@ -564,18 +567,65 @@ private synchronized void load() {
LOGGER.log(Level.SEVERE, "Failed to load the configuration from config path = "+config,e);
}
}
-
+
+ /**
+ * Represents the supported response formats (JSON, pretty JSON).
+ */
+ private enum ResponseFormat {
+ JSON("application/json;charset=UTF-8", false),
+ PRETTYJSON("application/json;charset=UTF-8", true);
+
+ private String contentType;
+
+ private boolean pretty;
+
+ private static final ResponseFormat DEFAULT = JSON;
+
+ private ResponseFormat(final String contentType, final boolean pretty) {
+ this.contentType = contentType;
+ this.pretty = pretty;
+ }
+
+ public static ResponseFormat fromAlias(final String alias) {
+ if (alias == null) {
+ return DEFAULT;
+ }
+ if (alias.equals("json")) {
+ return JSON;
+ } else if (alias.equals("json-pretty")) {
+ return PRETTYJSON;
+ } else {
+ throw new IllegalStateException("Unsupported format: " + alias);
+ }
+ }
+
+ public String getContentType() {
+ return contentType;
+ }
+
+ public boolean getPretty() {
+ return pretty;
+ }
+ }
+
/**
- * Serves the JSON response.
- * @param item Data to be serialized to JSON
- * @return HTTP response with application/json MIME type
+ * Serves the response and manages its output format in the response.
+ *
+ * @param item Data to be serialized
+ * @param format Format used in the response. See {@link ResponseFormat} for supported format.
+ *
+ * @return HTTP response with MIME type
*/
- private static HttpResponse toJSONResponse(final Object item) {
+ private static HttpResponse toFormattedResponse(final Object item, final String format) {
return new HttpResponse() {
@Override
public void generateResponse(StaplerRequest req, StaplerResponse rsp, Object node) throws IOException, ServletException {
- ObjectMapper mapper = new ObjectMapper();
- rsp.setContentType("application/json;charset=UTF-8");
+ ObjectMapper mapper = new ObjectMapper();
+ ResponseFormat responseFormat = ResponseFormat.fromAlias(format);
+ rsp.setContentType(responseFormat.getContentType());
+ if (responseFormat.getPretty()) {
+ mapper.enable(SerializationFeature.INDENT_OUTPUT);
+ }
mapper.writeValue(rsp.getWriter(), item);
}
};
diff --git a/docker-traceability-plugin/src/main/resources/org/jenkinsci/plugins/docker/traceability/core/DockerTraceabilityRootAction/_api.jelly b/docker-traceability-plugin/src/main/resources/org/jenkinsci/plugins/docker/traceability/core/DockerTraceabilityRootAction/_api.jelly
index 2664496..8ec2ba3 100644
--- a/docker-traceability-plugin/src/main/resources/org/jenkinsci/plugins/docker/traceability/core/DockerTraceabilityRootAction/_api.jelly
+++ b/docker-traceability-plugin/src/main/resources/org/jenkinsci/plugins/docker/traceability/core/DockerTraceabilityRootAction/_api.jelly
@@ -25,200 +25,227 @@
-->
Docker Deployment READ permission is required for all commands.
+Gets a container page. Jenkins will redirect the request to the fingerprint page, which addresses the specified container.
+Returns a HTML page describing the container's fingerprint track.
+Query Parameters:
idID of the container. Only full 64-symbol IDs are supportedGets an image page by its ID. Jenkins will redirect the request to the fingerprint page, which addresses the specified image.
+Returns a HTML page describing the image's fingerprint track.
+Query Parameters:
idID of the image. Only full 64-symbol IDs are supportedRetrieves the last available info about the container.
+Returns a JSON string similar to docker inspect $(containerId) output. Output is compatible with Docker API v.1.16
Query Parameters:
idID of the container. Only full 64-symbol IDs are supportedformatFormat used in the response. Supported values:
+ json (default value)json-prettyRetrieves the info about container.
+Returns: JSON string similar to docker inspect $(containerId) output.
Query Parameters:
+idID of the container. Only full 64-symbol IDs are supportedsinceThe time is specified in seconds since January 1, 1970, 00:00:00 GMTuntilThe time is specified in seconds since January 1, 1970, 00:00:00 GMTmodeDefines a data to be retrieved. Supported values:
inspectContaner (default)docker inspect $(containerId). Output is compatible with Docker API v.1.16inspectImagedocker inspect $(imageId). Output is compatible with Docker API v.1.16eventshostInfodocker infoallformatFormat used in the response. Supported values:
+ json (default value)json-prettyRetrieves the last available info about the container.
+Returns a JSON string similar to docker inspect $(imageId) output. Output is compatible with Docker API v.1.16
Query Parameters:
idID of the image. Only full 64-symbol IDs are supportedformatFormat used in the response. Supported values:
json (default value)json-prettyDocker Deployment SUBMIT permission is required for all commands.
+ +Allows to submit the current container status snapshot with a minimal set of
+ parameters. Outputs of docker inspect $(containerId) can be directly
+ submitted to Jenkins server using this command.
Parameters:
inspectDataJSON data being generated by docker inspect $(containerId)hostIdOptional ID of the source Docker host. Default value - "unknown"hostNameOptional ID of the source Docker host name. Default value - "unknown"statusOptional status of the container. Default value - "NONE" (means that there is no status change)timeOptional event time, the current server's time will be used by default. The time is specified in Unix timeimageNameOptional name of the image. It can be extracted from "docker images" command outputenvironmentOptional free-style string describing the environmentCall examples:
+curl http://localhost:8080/jenkins/docker-traceability/submitContainerStatus --data-urlencode inspectData="$(docker inspect CONTAINER_ID)"
+
+ Submits a report using the extended JSON API. This endpoint can be used by scripts to submit the full available info about the container and its environment in a single command.
+Parameters:
jsonJSON structure being generated by an external script, which includes all the available data regarding the container.This structure has the following entries:
+imageIdCall example (from test samples):
+curl http://localhost:8080/jenkins/docker-traceability/submitReport --data-urlencode json@src/test/resources/org/jenkinsci/plugins/docker/traceability/samples/submitReport.json
+ Removes an obsolete container reference from the DockerTraceability registry. + The data from container fingerprints won't be deleted, so the record will be + completely restored after a new submission if its gets deleted due to a mistake.
+Parameters:
+idID of the container. Only full 64-symbol IDs are supported