com.jcabi.manifests

Class Manifests

java.lang.Object

com.jcabi.manifests.Manifests

@Immutable
public final class Manifests
extends Object

Static reader of META-INF/MANIFEST.MF files. The class provides convenient methods to read all MANIFEST.MF files available in classpath and all attributes from them. This mechanism is very useful for transferring information from continuous integration environment to the production environment. For example, you want your site to show project version and the date of WAR file packaging. First, you configure maven-war-plugin to add this information to MANIFEST.MF:

 <plugin>
  <artifactId>maven-war-plugin</artifactId>
  <configuration>
   <archive>
    <manifestEntries>
     <Foo-Version>${project.version}</Foo-Version>
     <Foo-Date>${maven.build.timestamp}</Foo-Date>
    </manifestEntries>
   </archive>
  </configuration>
 </plugin>

maven-war-plugin will add these attributes to your MANIFEST.MF file and the project will be deployed to the production environment. Then, you can read these attributes where it's necessary (in one of your JAXB annotated objects, for example) and show to users:

 import com.jcabi.manifests.Manifest;
 import java.text.SimpleDateFormat;
 import java.util.Date;
 import java.util.Locale;
 import javax.xml.bind.annotation.XmlElement;
 import javax.xml.bind.annotation.XmlRootElement;
 @XmlRootElement
 public final class Page {
   @XmlElement
   public String version() {
     return Manifests.read("Foo-Version");
   }
   @XmlElement
   public Date date() {
     return new SimpleDateFormat("yyyy.MM.dd", Locale.ENGLISH).parse(
       Manifests.read("Foo-Date");
     );
   }
 }

In unit and integration tests you may need to inject some values to MANIFEST.MF in runtime (for example, in your bootstrap Groovy scripts):

 import com.jcabi.manifests.Manifests
 Manifests.inject("Foo-URL", "http://localhost/abc");

When it is necessary to isolate such injections between different unit tests "snapshots" may help, for example (it's a method in a unit test):

 @Test
 public void testSomeCode() {
   // save current state of all MANIFEST.MF attributes
   final byte[] snapshot = Manifests.snapshot();
   // inject new attribute required for this specific test
   Manifests.inject("Foo-URL", "http://localhost/abc");
   // restore back all attributes, as they were before the injection
   Manifests.revert(snapshot);
 }

The only dependency you need (check the latest version at jcabi-manifests):

 <dependency>
  <groupId>com.jcabi</groupId>
  <artifactId>jcabi-manifests</artifactId>
 </dependency>

Since:

0.7

Version:

$Id$

Author:

Yegor Bugayenko (yegor@tpc2.com)

See Also:

JAR Manifest, Maven Archiver, www.jcabi.com/jcabi-manifests

Method Summary

Methods

Modifier and Type	Method and Description
static void	append(File file) Append attributes from the file.
static void	append(InputStream stream) Append attributes from input stream.
static void	append(ServletContext ctx) Append attributes from the web application MANIFEST.MF.
static boolean	exists(String name) Check whether attribute exists in any of MANIFEST.MF files.
static void	inject(String name, String value) Inject new attribute.
static String	read(String name) Read one attribute available in one of MANIFEST.MF files.
static void	revert(byte[] snapshot) Revert to the state that was recorded by snapshot().
static byte[]	snapshot() Make a snapshot of current attributes and their values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

read

public static String read(@NotNull(message="attribute name can\'t be NULL")@Pattern(regexp=".+",message="attribute name can\'t be empty")
          String name)

Read one attribute available in one of MANIFEST.MF files.

If such a attribute doesn't exist IllegalArgumentException will be thrown. If you're not sure whether the attribute is present or not use exists(String) beforehand.

During testing you can inject attributes into this class by means of inject(String,String).

The method is thread-safe.

Parameters:

name - Name of the attribute

Returns:

The value of the attribute retrieved

inject

public static void inject(@NotNull(message="injected name can\'t be NULL")@Pattern(regexp=".+",message="name of attribute can\'t be empty")
          String name,
          @NotNull(message="inected value can\'t be NULL")
          String value)

Inject new attribute.

An attribute can be injected in runtime, mostly for the sake of unit and integration testing. Once injected an attribute becomes available with read(String).

The method is thread-safe.

Parameters:

name - Name of the attribute

value - The value of the attribute being injected

exists

public static boolean exists(@NotNull(message="name of attribute can\'t be NULL")@Pattern(regexp=".+",message="name of attribute can\'t be empty")
             String name)

Check whether attribute exists in any of MANIFEST.MF files.

Use this method before read(String) to check whether an attribute exists, in order to avoid a runtime exception.

The method is thread-safe.

Parameters:

name - Name of the attribute to check

Returns:

Returns TRUE if it exists, FALSE otherwise

snapshot

public static byte[] snapshot()

Make a snapshot of current attributes and their values.

The method is thread-safe.

Returns:

The snapshot, to be used later with revert(byte[])

revert

public static void revert(@NotNull(message="snapshot can\'t be NULL")
          byte[] snapshot)

Revert to the state that was recorded by snapshot().

The method is thread-safe.

Parameters:

snapshot - The snapshot taken by snapshot()

append

public static void append(@NotNull(message="servlet context can\'t be NULL")
          ServletContext ctx)
                   throws IOException

Append attributes from the web application MANIFEST.MF.

You can call this method in your own Filter or ServletContextListener, in order to inject MANIFEST.MF attributes to the class.

The method is thread-safe.

Parameters:

ctx - Servlet context

Throws:

IOException - If some I/O problem inside

See Also:

Manifests()

append

public static void append(@NotNull(message="file can\'t be NULL")
          File file)
                   throws IOException

Append attributes from the file.

The method is thread-safe.

Parameters:

file - The file to load attributes from

Throws:

IOException - If some I/O problem inside

append

public static void append(@NotNull(message="input stream can\'t be null")
          InputStream stream)
                   throws IOException

Append attributes from input stream.

The method is thread-safe.

Parameters:

stream - Stream to use

Throws:

IOException - If some I/O problem inside

Since:

0.8