View Javadoc

1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.http.util;
29  
30  import java.io.IOException;
31  import java.io.InputStream;
32  import java.util.List;
33  import java.util.Map;
34  import java.util.Properties;
35  import java.util.ArrayList;
36  
37  
38  /**
39   * Provides access to version information for HTTP components.
40   * Static methods are used to extract version information from property
41   * files that are automatically packaged with HTTP component release JARs.
42   * <br/>
43   * All available version information is provided in strings, where
44   * the string format is informal and subject to change without notice.
45   * Version information is provided for debugging output and interpretation
46   * by humans, not for automated processing in applications.
47   *
48   * @since 4.0
49   */
50  public class VersionInfo {
51  
52      /** A string constant for unavailable information. */
53      public final static String UNAVAILABLE = "UNAVAILABLE";
54  
55      /** The filename of the version information files. */
56      public final static String VERSION_PROPERTY_FILE = "version.properties";
57  
58      // the property names
59      public final static String PROPERTY_MODULE    = "info.module";
60      public final static String PROPERTY_RELEASE   = "info.release";
61      public final static String PROPERTY_TIMESTAMP = "info.timestamp";
62  
63  
64      /** The package that contains the version information. */
65      private final String infoPackage;
66  
67      /** The module from the version info. */
68      private final String infoModule;
69  
70      /** The release from the version info. */
71      private final String infoRelease;
72  
73      /** The timestamp from the version info. */
74      private final String infoTimestamp;
75  
76      /** The classloader from which the version info was obtained. */
77      private final String infoClassloader;
78  
79  
80      /**
81       * Instantiates version information.
82       *
83       * @param pckg      the package
84       * @param module    the module, or <code>null</code>
85       * @param release   the release, or <code>null</code>
86       * @param time      the build time, or <code>null</code>
87       * @param clsldr    the class loader, or <code>null</code>
88       */
89      protected VersionInfo(String pckg, String module,
90                            String release, String time, String clsldr) {
91          if (pckg == null) {
92              throw new IllegalArgumentException
93                  ("Package identifier must not be null.");
94          }
95  
96          infoPackage     = pckg;
97          infoModule      = (module  != null) ? module  : UNAVAILABLE;
98          infoRelease     = (release != null) ? release : UNAVAILABLE;
99          infoTimestamp   = (time    != null) ? time    : UNAVAILABLE;
100         infoClassloader = (clsldr  != null) ? clsldr  : UNAVAILABLE;
101     }
102 
103 
104     /**
105      * Obtains the package name.
106      * The package name identifies the module or informal unit.
107      *
108      * @return  the package name, never <code>null</code>
109      */
110     public final String getPackage() {
111         return infoPackage;
112     }
113 
114     /**
115      * Obtains the name of the versioned module or informal unit.
116      * This data is read from the version information for the package.
117      *
118      * @return  the module name, never <code>null</code>
119      */
120     public final String getModule() {
121         return infoModule;
122     }
123 
124     /**
125      * Obtains the release of the versioned module or informal unit.
126      * This data is read from the version information for the package.
127      *
128      * @return  the release version, never <code>null</code>
129      */
130     public final String getRelease() {
131         return infoRelease;
132     }
133 
134     /**
135      * Obtains the timestamp of the versioned module or informal unit.
136      * This data is read from the version information for the package.
137      *
138      * @return  the timestamp, never <code>null</code>
139      */
140     public final String getTimestamp() {
141         return infoTimestamp;
142     }
143 
144     /**
145      * Obtains the classloader used to read the version information.
146      * This is just the <code>toString</code> output of the classloader,
147      * since the version information should not keep a reference to
148      * the classloader itself. That could prevent garbage collection.
149      *
150      * @return  the classloader description, never <code>null</code>
151      */
152     public final String getClassloader() {
153         return infoClassloader;
154     }
155 
156 
157     /**
158      * Provides the version information in human-readable format.
159      *
160      * @return  a string holding this version information
161      */
162     @Override
163     public String toString() {
164         StringBuilder sb = new StringBuilder
165             (20 + infoPackage.length() + infoModule.length() +
166              infoRelease.length() + infoTimestamp.length() +
167              infoClassloader.length());
168 
169         sb.append("VersionInfo(")
170             .append(infoPackage).append(':').append(infoModule);
171 
172         // If version info is missing, a single "UNAVAILABLE" for the module
173         // is sufficient. Everything else just clutters the output.
174         if (!UNAVAILABLE.equals(infoRelease))
175             sb.append(':').append(infoRelease);
176         if (!UNAVAILABLE.equals(infoTimestamp))
177             sb.append(':').append(infoTimestamp);
178 
179         sb.append(')');
180 
181         if (!UNAVAILABLE.equals(infoClassloader))
182             sb.append('@').append(infoClassloader);
183 
184         return sb.toString();
185     }
186 
187 
188     /**
189      * Loads version information for a list of packages.
190      *
191      * @param pckgs     the packages for which to load version info
192      * @param clsldr    the classloader to load from, or
193      *                  <code>null</code> for the thread context classloader
194      *
195      * @return  the version information for all packages found,
196      *          never <code>null</code>
197      */
198     public final static VersionInfo[] loadVersionInfo(String[] pckgs,
199                                                       ClassLoader clsldr) {
200         if (pckgs == null) {
201             throw new IllegalArgumentException
202                 ("Package identifier list must not be null.");
203         }
204 
205         List<VersionInfo> vil = new ArrayList<VersionInfo>(pckgs.length);
206         for (int i=0; i<pckgs.length; i++) {
207             VersionInfo vi = loadVersionInfo(pckgs[i], clsldr);
208             if (vi != null)
209                 vil.add(vi);
210         }
211 
212         return vil.toArray(new VersionInfo[vil.size()]);
213     }
214 
215 
216     /**
217      * Loads version information for a package.
218      *
219      * @param pckg      the package for which to load version information,
220      *                  for example "org.apache.http".
221      *                  The package name should NOT end with a dot.
222      * @param clsldr    the classloader to load from, or
223      *                  <code>null</code> for the thread context classloader
224      *
225      * @return  the version information for the argument package, or
226      *          <code>null</code> if not available
227      */
228     public final static VersionInfo loadVersionInfo(final String pckg,
229                                                     ClassLoader clsldr) {
230         if (pckg == null) {
231             throw new IllegalArgumentException
232                 ("Package identifier must not be null.");
233         }
234 
235         if (clsldr == null)
236             clsldr = Thread.currentThread().getContextClassLoader();
237 
238         Properties vip = null; // version info properties, if available
239         try {
240             // org.apache.http      becomes
241             // org/apache/http/version.properties
242             InputStream is = clsldr.getResourceAsStream
243                 (pckg.replace('.', '/') + "/" + VERSION_PROPERTY_FILE);
244             if (is != null) {
245                 try {
246                     Properties props = new Properties();
247                     props.load(is);
248                     vip = props;
249                 } finally {
250                     is.close();
251                 }
252             }
253         } catch (IOException ex) {
254             // shamelessly munch this exception
255         }
256 
257         VersionInfo result = null;
258         if (vip != null)
259             result = fromMap(pckg, vip, clsldr);
260 
261         return result;
262     }
263 
264 
265     /**
266      * Instantiates version information from properties.
267      *
268      * @param pckg      the package for the version information
269      * @param info      the map from string keys to string values,
270      *                  for example {@link java.util.Properties}
271      * @param clsldr    the classloader, or <code>null</code>
272      *
273      * @return  the version information
274      */
275     protected final static VersionInfo fromMap(String pckg, Map<?, ?> info,
276                                                ClassLoader clsldr) {
277         if (pckg == null) {
278             throw new IllegalArgumentException
279                 ("Package identifier must not be null.");
280         }
281 
282         String module = null;
283         String release = null;
284         String timestamp = null;
285 
286         if (info != null) {
287             module = (String) info.get(PROPERTY_MODULE);
288             if ((module != null) && (module.length() < 1))
289                 module = null;
290 
291             release = (String) info.get(PROPERTY_RELEASE);
292             if ((release != null) && ((release.length() < 1) ||
293                                       (release.equals("${pom.version}"))))
294                 release = null;
295 
296             timestamp = (String) info.get(PROPERTY_TIMESTAMP);
297             if ((timestamp != null) &&
298                 ((timestamp.length() < 1) ||
299                  (timestamp.equals("${mvn.timestamp}")))
300                 )
301                 timestamp = null;
302         } // if info
303 
304         String clsldrstr = null;
305         if (clsldr != null)
306             clsldrstr = clsldr.toString();
307 
308         return new VersionInfo(pckg, module, release, timestamp, clsldrstr);
309     }
310 
311 } // class VersionInfo