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