001: /*
002: * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.0-beta1/module-main/src/main/java/org/apache/http/util/VersionInfo.java $
003: * $Revision: 554888 $
004: * $Date: 2007-07-10 11:46:36 +0200 (Tue, 10 Jul 2007) $
005: *
006: * ====================================================================
007: * Licensed to the Apache Software Foundation (ASF) under one
008: * or more contributor license agreements. See the NOTICE file
009: * distributed with this work for additional information
010: * regarding copyright ownership. The ASF licenses this file
011: * to you under the Apache License, Version 2.0 (the
012: * "License"); you may not use this file except in compliance
013: * with the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing,
018: * software distributed under the License is distributed on an
019: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
020: * KIND, either express or implied. See the License for the
021: * specific language governing permissions and limitations
022: * under the License.
023: * ====================================================================
024: *
025: * This software consists of voluntary contributions made by many
026: * individuals on behalf of the Apache Software Foundation. For more
027: * information on the Apache Software Foundation, please see
028: * <http://www.apache.org/>.
029: *
030: */
031:
032: package org.apache.http.util;
033:
034: import java.io.IOException;
035: import java.io.InputStream;
036: import java.util.Map;
037: import java.util.Properties;
038: import java.util.ArrayList;
039:
040: /**
041: * Provides access to version information for HTTP components.
042: * Instances of this class provide version information for a single module
043: * or informal unit, as explained
044: * <a href="http://wiki.apache.org/jakarta-httpclient/HttpComponents">here</a>.
045: * Static methods are used to extract version information from property
046: * files that are automatically packaged with HTTP component release JARs.
047: * <br/>
048: * All available version information is provided in strings, where
049: * the string format is informal and subject to change without notice.
050: * Version information is provided for debugging output and interpretation
051: * by humans, not for automated processing in applications.
052: *
053: * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
054: * @author and others
055: */
056: public class VersionInfo {
057:
058: /** A string constant for unavailable information. */
059: public final static String UNAVAILABLE = "UNAVAILABLE";
060:
061: /** The filename of the version information files. */
062: public final static String VERSION_PROPERTY_FILE = "version.properties";
063:
064: // the property names
065: public final static String PROPERTY_MODULE = "info.module";
066: public final static String PROPERTY_RELEASE = "info.release";
067: public final static String PROPERTY_TIMESTAMP = "info.timestamp";
068:
069: /** The package that contains the version information. */
070: private final String infoPackage;
071:
072: /** The module from the version info. */
073: private final String infoModule;
074:
075: /** The release from the version info. */
076: private final String infoRelease;
077:
078: /** The timestamp from the version info. */
079: private final String infoTimestamp;
080:
081: /** The classloader from which the version info was obtained. */
082: private final String infoClassloader;
083:
084: /**
085: * Instantiates version information.
086: *
087: * @param pckg the package
088: * @param module the module, or <code>null</code>
089: * @param release the release, or <code>null</code>
090: * @param time the build time, or <code>null</code>
091: * @param clsldr the class loader, or <code>null</code>
092: */
093: protected VersionInfo(String pckg, String module, String release,
094: String time, String clsldr) {
095: if (pckg == null) {
096: throw new IllegalArgumentException(
097: "Package identifier must not be null.");
098: }
099:
100: infoPackage = pckg;
101: infoModule = (module != null) ? module : UNAVAILABLE;
102: infoRelease = (release != null) ? release : UNAVAILABLE;
103: infoTimestamp = (time != null) ? time : UNAVAILABLE;
104: infoClassloader = (clsldr != null) ? clsldr : UNAVAILABLE;
105: }
106:
107: /**
108: * Obtains the package name.
109: * The package name identifies the module or informal unit.
110: *
111: * @return the package name, never <code>null</code>
112: */
113: public final String getPackage() {
114: return infoPackage;
115: }
116:
117: /**
118: * Obtains the name of the versioned module or informal unit.
119: * This data is read from the version information for the package.
120: *
121: * @return the module name, never <code>null</code>
122: */
123: public final String getModule() {
124: return infoModule;
125: }
126:
127: /**
128: * Obtains the release of the versioned module or informal unit.
129: * This data is read from the version information for the package.
130: *
131: * @return the release version, never <code>null</code>
132: */
133: public final String getRelease() {
134: return infoRelease;
135: }
136:
137: /**
138: * Obtains the timestamp of the versioned module or informal unit.
139: * This data is read from the version information for the package.
140: *
141: * @return the timestamp, never <code>null</code>
142: */
143: public final String getTimestamp() {
144: return infoTimestamp;
145: }
146:
147: /**
148: * Obtains the classloader used to read the version information.
149: * This is just the <code>toString</code> output of the classloader,
150: * since the version information should not keep a reference to
151: * the classloader itself. That could prevent garbage collection.
152: *
153: * @return the classloader description, never <code>null</code>
154: */
155: public final String getClassloader() {
156: return infoClassloader;
157: }
158:
159: /**
160: * Provides the version information in human-readable format.
161: *
162: * @return a string holding this version information
163: */
164: public String toString() {
165: StringBuffer sb = new StringBuffer(20 + infoPackage.length()
166: + infoModule.length() + infoRelease.length()
167: + infoTimestamp.length() + infoClassloader.length());
168:
169: sb.append("VersionInfo(").append(infoPackage).append(':')
170: .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: * Loads version information for a list of packages.
189: *
190: * @param pckgs the packages for which to load version info
191: * @param clsldr the classloader to load from, or
192: * <code>null</code> for the thread context classloader
193: *
194: * @return the version information for all packages found,
195: * never <code>null</code>
196: */
197: public final static VersionInfo[] loadVersionInfo(String[] pckgs,
198: ClassLoader clsldr) {
199: if (pckgs == null) {
200: throw new IllegalArgumentException(
201: "Package identifier list must not be null.");
202: }
203:
204: ArrayList vil = new ArrayList(pckgs.length);
205: for (int i = 0; i < pckgs.length; i++) {
206: VersionInfo vi = loadVersionInfo(pckgs[i], clsldr);
207: if (vi != null)
208: vil.add(vi);
209: }
210:
211: return (VersionInfo[]) vil.toArray(new VersionInfo[vil.size()]);
212: }
213:
214: /**
215: * Loads version information for a package.
216: *
217: * @param pckg the package for which to load version information,
218: * for example "org.apache.http".
219: * The package name should NOT end with a dot.
220: * @param clsldr the classloader to load from, or
221: * <code>null</code> for the thread context classloader
222: *
223: * @return the version information for the argument package, or
224: * <code>null</code> if not available
225: */
226: public final static VersionInfo loadVersionInfo(final String pckg,
227: ClassLoader clsldr) {
228: if (pckg == null) {
229: throw new IllegalArgumentException(
230: "Package identifier must not be null.");
231: }
232:
233: if (clsldr == null)
234: clsldr = Thread.currentThread().getContextClassLoader();
235:
236: Properties vip = null; // version info properties, if available
237: try {
238: // org.apache.http becomes
239: // org/apache/http/version.properties
240: InputStream is = clsldr.getResourceAsStream(pckg.replace(
241: '.', '/')
242: + "/" + VERSION_PROPERTY_FILE);
243: if (is != null) {
244: try {
245: Properties props = new Properties();
246: props.load(is);
247: vip = props;
248: } finally {
249: is.close();
250: }
251: }
252: } catch (IOException ex) {
253: // shamelessly munch this exception
254: }
255:
256: VersionInfo result = null;
257: if (vip != null)
258: result = fromMap(pckg, vip, clsldr);
259:
260: return result;
261: }
262:
263: /**
264: * Instantiates version information from properties.
265: *
266: * @param pckg the package for the version information
267: * @param info the map from string keys to string values,
268: * for example {@link java.util.Properties}
269: * @param clsldr the classloader, or <code>null</code>
270: *
271: * @return the version information
272: */
273: protected final static VersionInfo fromMap(String pckg, Map info,
274: ClassLoader clsldr) {
275: if (pckg == null) {
276: throw new IllegalArgumentException(
277: "Package identifier must not be null.");
278: }
279:
280: String module = null;
281: String release = null;
282: String timestamp = null;
283:
284: if (info != null) {
285: module = (String) info.get(PROPERTY_MODULE);
286: if ((module != null) && (module.length() < 1))
287: module = null;
288:
289: release = (String) info.get(PROPERTY_RELEASE);
290: if ((release != null)
291: && ((release.length() < 1) || (release
292: .equals("${pom.version}"))))
293: release = null;
294:
295: timestamp = (String) info.get(PROPERTY_TIMESTAMP);
296: if ((timestamp != null)
297: && ((timestamp.length() < 1) || (timestamp
298: .equals("${mvn.timestamp}"))))
299: timestamp = null;
300: } // if info
301:
302: String clsldrstr = null;
303: if (clsldr != null)
304: clsldrstr = clsldr.toString();
305:
306: return new VersionInfo(pckg, module, release, timestamp,
307: clsldrstr);
308: }
309:
310: } // class VersionInfo
|