Debian Codegraph @

bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/metadata/Version.java

raw
1 /*******************************************************************************
2 * Copyright (c) 2009, 2017 Cloudsmith and others.
3 *
4 * This program and the accompanying materials
5 * are made available under the terms of the Eclipse Public License 2.0
6 * which accompanies this distribution, and is available at
7 * https://www.eclipse.org/legal/epl-2.0/
8 *
9 * SPDX-License-Identifier: EPL-2.0
10 *
11 * Contributors:
12 * Cloudsmith Inc - initial API and implementation.
13 *******************************************************************************/
14
15 package org.eclipse.equinox.p2.metadata;
16
17 import java.io.Serializable;
18 import java.lang.ref.SoftReference;
19 import java.util.WeakHashMap;
20 import org.eclipse.equinox.internal.p2.metadata.*;
21
22 /**
23 * A class that represents a Version in the Omni Version format. A Version can be thought of as an
24 * array of comparable elements and an optional pad value. The pad value is used when comparing
25 * two versions with a different number of segments.
26 *
27 * The Omni Version can convert almost any version into a raw format that it uses for comparisons.
28 * This enables a unified order of all such versions and solves problems that arise when the
29 * version semantics are different. A good example is the OSGi version versus the version used in Maven.
30 * The lack of qualifier in the OSGi version implies that the qualifier is an empty string. So a version
31 * without a qualifier is the smallest of all other versions with the same major,minor,micro number.
32 * With Maven semantics, it's the opposite. If the qualifier is removed, the resulting version is
33 * considered higher then all other versions with the same major, minor, and micro number. The
34 * Omni version solves this by using different raw representations of the OSGi and Maven versions.
35 *
36 * The Omni version addresses a lot of other issues as well, such as reordering of the elements
37 * or treating some parts of a version as irrelevant when comparing.
38 *
39 * The class is signature compatible with {@link org.osgi.framework.Version} but attempts
40 * to use it as such might render a {@link UnsupportedOperationException} in case the
41 * raw vector holds incompatible values. The method {@link #isOSGiCompatible()} can be used
42 * to test.
43 * @noextend This class is not intended to be subclassed by clients.
44 * @since 2.0
45 */
46 public abstract class Version implements Comparable<Version>, Serializable {
47 public static final String RAW_PREFIX = "raw:"; //$NON-NLS-1$
48 private static WeakHashMap<String, SoftReference<Version>> POOL = new WeakHashMap<>();
49
50 /**
51 * The version that is semantically greater then all other versions.
52 */
53 public static final Version MAX_VERSION = OmniVersion.createMaxVersion();
54
55 /**
56 * The version that is semantically less then all other versions.
57 */
58 public static final Version emptyVersion = OmniVersion.createMinVersion();
59
60 private static final long serialVersionUID = 6218979149720923857L;
61
62 /**
63 * Compile a version format string into a compiled format..
64 *
65 * @param format The format to compile.
66 * @return The compiled format
67 * @throws VersionFormatException If the format could not be compiled
68 */
69 public static IVersionFormat compile(String format) throws VersionFormatException {
70 return VersionFormat.compile(format, 0, format.length());
71 }
72
73 /**
74 * Parses a version identifier from the specified string.
75 * <p>
76 * Note that this method performs a non thread-safe object pooling. Instances are
77 * stored in a weak cache, i.e. for multiple calls with the same input it is likely
78 * but not guaranteed that the same instance is retrieved. Same holds for concurrent
79 * access on this method. Clients must not assume to get the same instance for
80 * subsequent calls.
81 *
82 * @param version String representation of the version identifier. Leading
83 * and trailing whitespace will be ignored.
84 * @return A <code>Version</code> object representing the version identifier
85 * or <code>null</code> if <code>version</code> is <code>null</code> or
86 * an empty string.
87 * @throws IllegalArgumentException If <code>version</code> is improperly
88 * formatted.
89 */
90 public static Version create(String version) {
91 Version v = null;
92 if (version != null && version.length() > 0) {
93 SoftReference<Version> vRef = POOL.get(version);
94 v = vRef != null ? vRef.get() : null;
95 if (v == null) {
96 v = VersionParser.parse(version, 0, version.length());
97 synchronized (POOL) {
98 POOL.put(version, new SoftReference<>(v));
99 }
100 }
101 }
102 return v;
103 }
104
105 /**
106 * Creates an OSGi version identifier from the specified numerical components.
107 *
108 * <p>
109 * The qualifier is set to the empty string.
110 *
111 * @param major Major component of the version identifier.
112 * @param minor Minor component of the version identifier.
113 * @param micro Micro component of the version identifier.
114 * @throws IllegalArgumentException If the numerical components are
115 * negative.
116 */
117 public static Version createOSGi(int major, int minor, int micro) {
118 return createOSGi(major, minor, micro, null);
119 }
120
121 /**
122 * Creates an OSGi version identifier from the specified components.
123 *
124 * @param major Major component of the version identifier.
125 * @param minor Minor component of the version identifier.
126 * @param micro Micro component of the version identifier.
127 * @param qualifier Qualifier component of the version identifier. If
128 * <code>null</code> is specified, then the qualifier will be set to
129 * the empty string.
130 * @throws IllegalArgumentException If the numerical components are negative
131 * or the qualifier string is invalid.
132 */
133 public static Version createOSGi(int major, int minor, int micro, String qualifier) {
134 Comparable<?> logicQualifier;
135 if (qualifier == null || qualifier.length() == 0) {
136 if (major == 0 && minor == 0 && micro == 0)
137 return emptyVersion;
138 logicQualifier = VersionVector.MINS_VALUE; // So that we can do identity compare
139 } else if (qualifier.equals(IVersionFormat.DEFAULT_MAX_STRING_TRANSLATION))
140 logicQualifier = VersionVector.MAXS_VALUE;
141 else
142 logicQualifier = qualifier;
143 return new OSGiVersion(major, minor, micro, logicQualifier);
144 }
145
146 /**
147 * Parses a version identifier from the specified string. This method is for backward
148 * compatibility with OSGi and will return the OSGi &quot;0.0.0&quot; version when
149 * the provided string is empty or <code>null</code>.
150 *
151 * @param version String representation of the version identifier. Leading
152 * and trailing whitespace will be ignored.
153 * @return A <code>Version</code> object representing the version
154 * identifier. If <code>version</code> is <code>null</code> or
155 * the empty string then the OSGi <code>emptyVersion</code> will be
156 * returned.
157 * @throws IllegalArgumentException If <code>version</code> is improperly
158 * formatted.
159 * @see #create(String)
160 */
161 public static Version parseVersion(String version) {
162 if (version == null || version.length() == 0)
163 return Version.emptyVersion;
164 Version v = create(version);
165 return v == null ? Version.emptyVersion : v;
166 }
167
168 /**
169 * Returns the optional format.
170 */
171 public abstract IVersionFormat getFormat();
172
173 /**
174 * Returns the <code>original</code> part of the string for this version
175 * or <code>null</code> if no such part was provided when the version was
176 * created. An OSGi type version will always return the OSGi string representation.
177 *
178 * @return The <code>original</code> part of the version string or
179 * <code>null</code> if that part was missing.
180 */
181 public abstract String getOriginal();
182
183 /**
184 * Returns the pad value used when comparing this versions to
185 * versions that has a larger number of segments
186 * @return The pad value or <code>null</code> if not set.
187 */
188 public abstract Comparable<?> getPad();
189
190 /**
191 * An element from the raw vector representation of this version.
192 * @param index The zero based index of the desired element
193 * @return An element from the raw vector
194 */
195 public abstract Comparable<?> getSegment(int index);
196
197 /**
198 * Returns the number of elements in the raw vector representation of this version.
199 * @return The number of elements in the raw vector.
200 */
201 public abstract int getSegmentCount();
202
203 /**
204 * Checks if this version is in compliance with the OSGi version spec.
205 * @return A flag indicating whether the version is OSGi compatible or not.
206 */
207 public abstract boolean isOSGiCompatible();
208
209 @Override
210 public String toString() {
211 StringBuffer buf = new StringBuffer(20);
212 toString(buf);
213 return buf.toString();
214 }
215
216 /**
217 * Appends the string representation of this version onto the
218 * <code>sb</code> StringBuffer.
219 * @param sb The buffer that will receive the version string
220 */
221 public abstract void toString(StringBuffer sb);
222 }