Debian Codegraph @

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

raw
1 /*******************************************************************************
2 * Copyright (c) 2007, 2018 IBM Corporation 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 * IBM Corporation - initial API and implementation
13 * Genuitec, LLC
14 * EclipseSource - ongoing development
15 *******************************************************************************/
16 package org.eclipse.equinox.p2.metadata;
17
18 import java.net.URI;
19 import java.util.ArrayList;
20 import java.util.Arrays;
21 import java.util.Collection;
22 import java.util.Collections;
23 import java.util.HashMap;
24 import java.util.LinkedHashMap;
25 import java.util.List;
26 import java.util.Map;
27 import org.eclipse.core.runtime.Assert;
28 import org.eclipse.equinox.internal.p2.metadata.Copyright;
29 import org.eclipse.equinox.internal.p2.metadata.IRequiredCapability;
30 import org.eclipse.equinox.internal.p2.metadata.InstallableUnit;
31 import org.eclipse.equinox.internal.p2.metadata.InstallableUnitFragment;
32 import org.eclipse.equinox.internal.p2.metadata.InstallableUnitPatch;
33 import org.eclipse.equinox.internal.p2.metadata.License;
34 import org.eclipse.equinox.internal.p2.metadata.ProvidedCapability;
35 import org.eclipse.equinox.internal.p2.metadata.RequiredCapability;
36 import org.eclipse.equinox.internal.p2.metadata.RequiredPropertiesMatch;
37 import org.eclipse.equinox.internal.p2.metadata.Requirement;
38 import org.eclipse.equinox.internal.p2.metadata.RequirementChange;
39 import org.eclipse.equinox.internal.p2.metadata.ResolvedInstallableUnit;
40 import org.eclipse.equinox.internal.p2.metadata.TouchpointData;
41 import org.eclipse.equinox.internal.p2.metadata.TouchpointInstruction;
42 import org.eclipse.equinox.internal.p2.metadata.TouchpointType;
43 import org.eclipse.equinox.internal.p2.metadata.UpdateDescriptor;
44 import org.eclipse.equinox.p2.metadata.expression.ExpressionUtil;
45 import org.eclipse.equinox.p2.metadata.expression.IFilterExpression;
46 import org.eclipse.equinox.p2.metadata.expression.IMatchExpression;
47
48 /**
49 * A factory class for instantiating various p2 metadata objects.
50 *
51 * @since 2.0
52 */
53 public final class MetadataFactory {
54 /**
55 * A description containing information about an installable unit. Once created,
56 * installable units are immutable. This description class allows a client to
57 * build up the state for an installable unit incrementally, and then finally
58 * produce the resulting immutable unit.
59 */
60 public static class InstallableUnitDescription {
61 InstallableUnit unit;
62
63 /**
64 * A property key (value <code>"org.eclipse.equinox.p2.type.patch"</code>) for a
65 * boolean property indicating that an installable unit is a group.
66 *
67 */
68 public static final String PROP_TYPE_GROUP = "org.eclipse.equinox.p2.type.group"; //$NON-NLS-1$
69
70 /**
71 * A property key (value <code>"org.eclipse.equinox.p2.type.patch"</code>) for a
72 * boolean property indicating that an installable unit is a patch.
73 *
74 */
75 public static final String PROP_TYPE_PATCH = "org.eclipse.equinox.p2.type.patch"; //$NON-NLS-1$
76
77 /**
78 * A property key (value <code>"org.eclipse.equinox.p2.type.fragment"</code>)
79 * for a boolean property indicating that an installable unit is a fragment.
80 *
81 */
82 public static final String PROP_TYPE_FRAGMENT = "org.eclipse.equinox.p2.type.fragment"; //$NON-NLS-1$
83
84 /**
85 * A property key (value <code>"org.eclipse.equinox.p2.type.category"</code>)
86 * for a boolean property indicating that an installable unit is a category.
87 *
88 */
89 public static final String PROP_TYPE_CATEGORY = "org.eclipse.equinox.p2.type.category"; //$NON-NLS-1$
90
91 /**
92 * A property key (value <code>"org.eclipse.equinox.p2.type.product"</code>) for
93 * a boolean property indicating that an installable unit is the root IU of a
94 * product.
95 *
96 * @since 2.2
97 */
98 public static final String PROP_TYPE_PRODUCT = "org.eclipse.equinox.p2.type.product"; //$NON-NLS-1$
99
100 public InstallableUnitDescription() {
101 super();
102 }
103
104 /**
105 * Add the specified capabilities to the installable unit.
106 *
107 * @param additional the capabilities to add.
108 */
109 public void addProvidedCapabilities(Collection<IProvidedCapability> additional) {
110 if (additional == null || additional.size() == 0)
111 return;
112 Collection<IProvidedCapability> current = unit().getProvidedCapabilities();
113 ArrayList<IProvidedCapability> all = new ArrayList<>(additional.size() + current.size());
114 all.addAll(current);
115 all.addAll(additional);
116 unit().setCapabilities(all.toArray(new IProvidedCapability[all.size()]));
117 }
118
119 /** @deprecated Use addRequirements(additional) instead */
120 @Deprecated
121 public void addRequiredCapabilities(Collection<IRequirement> additional) {
122 addRequirements(additional);
123 }
124
125 /**
126 * Add the specified requirements to the installable unit.
127 *
128 * @param additional the requirements to add
129 */
130 public void addRequirements(Collection<IRequirement> additional) {
131 if (additional == null || additional.size() == 0)
132 return;
133 List<IRequirement> current = unit().getRequirements();
134 ArrayList<IRequirement> all = new ArrayList<>(additional.size() + current.size());
135 all.addAll(current);
136 all.addAll(additional);
137 unit().setRequiredCapabilities(all.toArray(new IRequirement[all.size()]));
138 }
139
140 public void addTouchpointData(ITouchpointData data) {
141 Assert.isNotNull(data);
142 unit().addTouchpointData(data);
143 }
144
145 /**
146 * Returns the id of the installable unit.
147 */
148 public String getId() {
149 return unit().getId();
150 }
151
152 /**
153 * Return a collection of all the capabilities specified on this installable
154 * unit.
155 */
156 public Collection<IProvidedCapability> getProvidedCapabilities() {
157 return unit().getProvidedCapabilities();
158 }
159
160 /** @deprecated Use getRequirements() instead */
161 @Deprecated
162 public List<IRequirement> getRequiredCapabilities() {
163 return getRequirements();
164 }
165
166 /**
167 * Return a collection of the requirements specified on this installable unit.
168 */
169 public List<IRequirement> getRequirements() {
170 return unit().getRequirements();
171 }
172
173 /** @deprecated Use getMetaRequirements() instead */
174 @Deprecated
175 public Collection<IRequirement> getMetaRequiredCapabilities() {
176 return getMetaRequirements();
177 }
178
179 /**
180 * Return a collection of the meta requirements specified on this installable
181 * unit.
182 */
183 public Collection<IRequirement> getMetaRequirements() {
184 return unit().getMetaRequirements();
185 }
186
187 /**
188 * Returns the current touchpoint data on this installable unit description. The
189 * touchpoint data may change if further data is added to the description.
190 *
191 * @return The current touchpoint data on this description
192 */
193 public Collection<ITouchpointData> getTouchpointData() {
194 return unit().getTouchpointData();
195
196 }
197
198 /**
199 * Return the versiono on this installable unit description.
200 */
201 public Version getVersion() {
202 return unit().getVersion();
203 }
204
205 /**
206 * Returns the UpdateDescriptor for this IU
207 *
208 * @since 2.1
209 */
210 public IUpdateDescriptor getUpdateDescriptor() {
211 return unit().getUpdateDescriptor();
212 }
213
214 /**
215 * Set the artifact keys for the installable unit. Previous values will be
216 * overwritten.
217 *
218 * @param value the artifacts to the used.
219 */
220 public void setArtifacts(IArtifactKey[] value) {
221 unit().setArtifacts(value);
222 }
223
224 /**
225 * Set the capabilities for the installable unit. Previous values will be
226 * overwritten.
227 *
228 * @param exportedCapabilities the capabilities to be used.
229 */
230 public void setCapabilities(IProvidedCapability[] exportedCapabilities) {
231 unit().setCapabilities(exportedCapabilities);
232 }
233
234 /**
235 * Set the copyright for the installable unit. Previous values will be
236 * overwritten.
237 *
238 * @param copyright the copyright to be used.
239 */
240 public void setCopyright(ICopyright copyright) {
241 unit().setCopyright(copyright);
242 }
243
244 public void setFilter(IMatchExpression<IInstallableUnit> filter) {
245 unit().setFilter(filter);
246 }
247
248 public void setFilter(String filter) {
249 unit().setFilter(filter);
250 }
251
252 /**
253 * Set the id of the installable unit.
254 */
255 public void setId(String id) {
256 unit().setId(id);
257 }
258
259 /**
260 * Set the licenses for the installable unit. Previous values will be
261 * overwritten.
262 */
263 public void setLicenses(ILicense[] licenses) {
264 unit().setLicenses(licenses);
265 }
266
267 /**
268 * Set a property with a specified value for this installable unit.
269 *
270 * @param key key with which the specified value is to be associated
271 * @param value value to be associated with the specified key
272 */
273 public void setProperty(String key, String value) {
274 unit().setProperty(key, value);
275 }
276
277 /** @deprecated Use setRequirements(requirements) instead */
278 @Deprecated
279 public void setRequiredCapabilities(IRequirement[] requirements) {
280 setRequirements(requirements);
281 }
282
283 /**
284 * Set the requirements for the installable unit. Previous values will be
285 * overwritten.
286 *
287 * @param requirements the requirements to be used.
288 */
289 public void setRequirements(IRequirement[] requirements) {
290 unit().setRequiredCapabilities(requirements);
291 }
292
293 /** @deprecated Use setMetaRequirements(requirements) instead */
294 @Deprecated
295 public void setMetaRequiredCapabilities(IRequirement[] metaRequirements) {
296 setMetaRequirements(metaRequirements);
297 }
298
299 /**
300 * Set the meta requirements for the installable unit. Previous values will be
301 * overwritten.
302 *
303 * @param metaRequirements the meta requirements to be used.
304 */
305 public void setMetaRequirements(IRequirement[] metaRequirements) {
306 unit().setMetaRequiredCapabilities(metaRequirements);
307 }
308
309 /**
310 * Change the singleton status of the installable unit.
311 */
312 public void setSingleton(boolean singleton) {
313 unit().setSingleton(singleton);
314 }
315
316 /**
317 * Set the touchpoint type for the installable unit.
318 */
319 public void setTouchpointType(ITouchpointType type) {
320 unit().setTouchpointType(type);
321 }
322
323 /**
324 * Set the update descriptor for the installable unit.
325 */
326 public void setUpdateDescriptor(IUpdateDescriptor updateInfo) {
327 unit().setUpdateDescriptor(updateInfo);
328 }
329
330 /**
331 * Set the version of this installable unit.
332 *
333 * @param newVersion version to be set on the installable unit.
334 */
335 public void setVersion(Version newVersion) {
336 unit().setVersion(newVersion);
337 }
338
339 InstallableUnit unit() {
340 if (unit == null) {
341 unit = new InstallableUnit();
342 unit.setArtifacts(new IArtifactKey[0]);
343 }
344 return unit;
345 }
346
347 IInstallableUnit unitCreate() {
348 IInstallableUnit result = unit();
349 this.unit = null;
350 return result;
351 }
352 }
353
354 /**
355 * A description containing information about an installable unit fragment. Once
356 * created, installable units are immutable. This description class allows a
357 * client to build up the state for an installable unit fragment incrementally,
358 * and then finally produce the resulting immutable unit.
359 */
360 public static class InstallableUnitFragmentDescription extends InstallableUnitDescription {
361 public InstallableUnitFragmentDescription() {
362 super();
363 setProperty(InstallableUnitDescription.PROP_TYPE_FRAGMENT, Boolean.TRUE.toString());
364 }
365
366 /**
367 * Specify the requirements identifying the host to which the installable unit
368 * fragment should be attached to.
369 */
370 public void setHost(IRequirement... hostRequirement) {
371 ((InstallableUnitFragment) unit()).setHost(Arrays.asList(hostRequirement));
372 }
373
374 @Override
375 InstallableUnit unit() {
376 if (unit == null)
377 unit = new InstallableUnitFragment();
378 return unit;
379 }
380 }
381
382 /**
383 * A description containing information about an installable unit patch. Once
384 * created, installable units are immutable. This description class allows a
385 * client to build up the state for an installable unit patch incrementally, and
386 * then finally produce the resulting immutable unit.
387 */
388 public static class InstallableUnitPatchDescription extends InstallableUnitDescription {
389
390 public InstallableUnitPatchDescription() {
391 super();
392 setProperty(InstallableUnitDescription.PROP_TYPE_PATCH, Boolean.TRUE.toString());
393 }
394
395 /**
396 * Set the applicability scope for the installable unit patch.
397 */
398 public void setApplicabilityScope(IRequirement[][] applyTo) {
399 if (applyTo == null)
400 throw new IllegalArgumentException("A patch scope can not be null"); //$NON-NLS-1$
401 ((InstallableUnitPatch) unit()).setApplicabilityScope(applyTo);
402 }
403
404 /**
405 * Set the lifecycle change for the installable unit patch.
406 */
407 public void setLifeCycle(IRequirement lifeCycle) {
408 ((InstallableUnitPatch) unit()).setLifeCycle(lifeCycle);
409 }
410
411 /**
412 * Set the requirement change for the installable unit patch.
413 */
414 public void setRequirementChanges(IRequirementChange[] changes) {
415 ((InstallableUnitPatch) unit()).setRequirementsChange(changes);
416 }
417
418 @Override
419 InstallableUnit unit() {
420 if (unit == null) {
421 unit = new InstallableUnitPatch();
422 ((InstallableUnitPatch) unit()).setApplicabilityScope(new IRequirement[0][0]);
423 }
424 return unit;
425 }
426 }
427
428 /**
429 * Singleton touchpoint data for a touchpoint with no instructions.
430 */
431 private static final ITouchpointData EMPTY_TOUCHPOINT_DATA = new TouchpointData(Collections.emptyMap());
432
433 private static ITouchpointType[] typeCache = new ITouchpointType[5];
434
435 private static int typeCacheOffset;
436
437 /**
438 * Returns an {@link IInstallableUnit} based on the given description. Once the
439 * installable unit has been created, the information is discarded from the
440 * description object.
441 *
442 * @param description The description of the unit to create
443 * @return The created installable unit
444 */
445 public static IInstallableUnit createInstallableUnit(InstallableUnitDescription description) {
446 Assert.isNotNull(description);
447 return description.unitCreate();
448 }
449
450 /**
451 * Returns an {@link IInstallableUnitFragment} based on the given description.
452 * Once the fragment has been created, the information is discarded from the
453 * description object.
454 *
455 * @param description The description of the unit to create
456 * @return The created installable unit fragment
457 */
458 public static IInstallableUnitFragment createInstallableUnitFragment(
459 InstallableUnitFragmentDescription description) {
460 Assert.isNotNull(description);
461 return (IInstallableUnitFragment) description.unitCreate();
462 }
463
464 /**
465 * Returns an {@link IInstallableUnitPatch} based on the given description. Once
466 * the patch installable unit has been created, the information is discarded
467 * from the description object.
468 *
469 * @param description The description of the unit to create
470 * @return The created installable unit patch
471 */
472 public static IInstallableUnitPatch createInstallableUnitPatch(InstallableUnitPatchDescription description) {
473 Assert.isNotNull(description);
474 return (IInstallableUnitPatch) description.unitCreate();
475 }
476
477 /**
478 * Returns a {@link IProvidedCapability} with the given values.
479 *
480 * @param namespace The capability namespace
481 * @param name The capability name
482 * @param version The capability version
483 */
484 public static IProvidedCapability createProvidedCapability(String namespace, String name, Version version) {
485 return new ProvidedCapability(namespace, name, version);
486 }
487
488 /**
489 * Returns a {@link IProvidedCapability} with the given values.
490 *
491 * @param namespace The capability namespace
492 * @param properties The description of the capability
493 * @since 2.4
494 */
495 public static IProvidedCapability createProvidedCapability(String namespace, Map<String, Object> properties) {
496 return new ProvidedCapability(namespace, properties);
497 }
498
499 /**
500 * Create and return a new requirement ({@link IRequirement}) with the specified
501 * values.
502 *
503 * @param namespace the namespace for the requirement. Must not be
504 * <code>null</code>.
505 * @param name the name for the requirement. Must not be <code>null</code>.
506 * @param range the version range. A value of <code>null</code> is
507 * equivalent to {@link VersionRange#emptyRange} and matches
508 * all versions.
509 * @param filter The filter used to evaluate whether this capability is
510 * applicable in the current environment, or <code>null</code>
511 * to indicate this capability is always applicable
512 * @param optional <code>true</code> if this requirement is optional, and
513 * <code>false</code> otherwise.
514 * @param multiple <code>true</code> if this requirement can be satisfied by
515 * multiple provided capabilities, or <code>false</code> if it
516 * requires exactly one match
517 * @param greedy <code>true</code> if the requirement should be considered
518 * greedy and <code>false</code> otherwise
519 * @return the requirement
520 */
521 public static IRequirement createRequirement(String namespace, String name, VersionRange range, String filter,
522 boolean optional, boolean multiple, boolean greedy) {
523 return new RequiredCapability(namespace, name, range, InstallableUnit.parseFilter(filter), optional ? 0 : 1,
524 multiple ? Integer.MAX_VALUE : 1, greedy, null);
525 }
526
527 /**
528 * Returns a {@link IRequirement} with the given values.
529 *
530 * @param namespace The capability namespace
531 * @param name The required capability name
532 * @param range The range of versions that are required, or
533 * <code>null</code> to indicate that any version will do.
534 * @param filter The filter used to evaluate whether this capability is
535 * applicable in the current environment, or <code>null</code>
536 * to indicate this capability is always applicable
537 * @param optional <code>true</code> if this required capability is optional,
538 * and <code>false</code> otherwise.
539 * @param multiple <code>true</code> if this capability can be satisfied by
540 * multiple provided capabilities, or <code>false</code> if it
541 * requires exactly one match
542 * @return the requirement
543 */
544 public static IRequirement createRequirement(String namespace, String name, VersionRange range,
545 IMatchExpression<IInstallableUnit> filter, boolean optional, boolean multiple) {
546 return new RequiredCapability(namespace, name, range, filter, optional ? 0 : 1,
547 multiple ? Integer.MAX_VALUE : 1, true, null);
548 }
549
550 /**
551 * Create and return a new requirement ({@link IRequirement}) with the specified
552 * values.
553 *
554 * @param namespace the namespace for the requirement. Must not be
555 * <code>null</code>.
556 * @param name the name for the requirement. Must not be <code>null</code>.
557 * @param range the version range. A value of <code>null</code> is
558 * equivalent to {@link VersionRange#emptyRange} and matches
559 * all versions.
560 * @param filter The filter used to evaluate whether this capability is
561 * applicable in the current environment, or <code>null</code>
562 * to indicate this capability is always applicable
563 * @param minCard minimum cardinality
564 * @param maxCard maximum cardinality
565 * @param greedy <code>true</code> if the requirement should be considered
566 * greedy and <code>false</code> otherwise
567 * @return the requirement
568 */
569 public static IRequirement createRequirement(String namespace, String name, VersionRange range,
570 IMatchExpression<IInstallableUnit> filter, int minCard, int maxCard, boolean greedy) {
571 return new RequiredCapability(namespace, name, range, filter, minCard, maxCard, greedy, null);
572 }
573
574 /**
575 * Create and return a new requirement ({@link IRequirement}) with the specified
576 * values.
577 *
578 * @param namespace the namespace for the requirement. Must not be
579 * <code>null</code>.
580 * @param name the name for the requirement. Must not be
581 * <code>null</code>.
582 * @param range the version range. A value of <code>null</code> is
583 * equivalent to {@link VersionRange#emptyRange} and matches
584 * all versions.
585 * @param filter The filter used to evaluate whether this capability is
586 * applicable in the current environment, or
587 * <code>null</code> to indicate this capability is always
588 * applicable
589 * @param minCard minimum cardinality
590 * @param maxCard maximum cardinality
591 * @param greedy <code>true</code> if the requirement should be considered
592 * greedy and <code>false</code> otherwise
593 * @param description a <code>String</code> description of the requirement, or
594 * <code>null</code>
595 * @return the requirement
596 */
597 public static IRequirement createRequirement(String namespace, String name, VersionRange range,
598 IMatchExpression<IInstallableUnit> filter, int minCard, int maxCard, boolean greedy, String description) {
599 return new RequiredCapability(namespace, name, range, filter, minCard, maxCard, greedy, description);
600 }
601
602 /**
603 *
604 * @param namespace the namespace for the requirement. Must not be
605 * <code>null</code>.
606 * @param propsFilter filter applied on
607 * {@link IProvidedCapability#getProperties()} of every
608 * {@link IInstallableUnit#getProvidedCapabilities()}
609 * @param envFilter matcher over {@link IInstallableUnit#getProperties()}
610 * @param minCard minimum cardinality
611 * @param maxCard maximum cardinality
612 * @param greedy <code>true</code> if the requirement should be considered
613 * greedy and <code>false</code> otherwise
614 * @return the requirement
615 * @since 2.4
616 */
617 public static IRequirement createRequirement(String namespace, String propsFilter,
618 IMatchExpression<IInstallableUnit> envFilter, int minCard, int maxCard, boolean greedy) {
619 IFilterExpression attrFilterExpr = ExpressionUtil.parseLDAP(propsFilter);
620 return new RequiredPropertiesMatch(namespace, attrFilterExpr, envFilter, minCard, maxCard, greedy, null);
621 }
622
623 /**
624 *
625 * @param namespace the namespace for the requirement. Must not be
626 * <code>null</code>.
627 * @param propsFilter filter applied on
628 * {@link IProvidedCapability#getProperties()} of every
629 * {@link IInstallableUnit#getProvidedCapabilities()}
630 * @param envFilter matcher over {@link IInstallableUnit#getProperties()}
631 * @param minCard minimum cardinality
632 * @param maxCard maximum cardinality
633 * @param greedy <code>true</code> if the requirement should be considered
634 * greedy and <code>false</code> otherwise
635 * @return the requirement
636 * @since 2.5
637 */
638 public static IRequirement createRequirement(String namespace, String propsFilter,
639 IMatchExpression<IInstallableUnit> envFilter, int minCard, int maxCard, boolean greedy,
640 String description) {
641 IFilterExpression attrFilterExpr = ExpressionUtil.parseLDAP(propsFilter);
642 return new RequiredPropertiesMatch(namespace, attrFilterExpr, envFilter, minCard, maxCard, greedy, description);
643 }
644
645 /**
646 *
647 * @param namespace the namespace for the requirement. Must not be
648 * <code>null</code>.
649 * @param propsFilter filter applied on
650 * {@link IProvidedCapability#getProperties()} of every
651 * {@link IInstallableUnit#getProvidedCapabilities()}
652 * @param envFilter matcher over {@link IInstallableUnit#getProperties()}
653 * @param minCard minimum cardinality
654 * @param maxCard maximum cardinality
655 * @param greedy <code>true</code> if the requirement should be considered
656 * greedy and <code>false</code> otherwise
657 * @param description a <code>String</code> description of the requirement, or
658 * <code>null</code>
659 * @return the requirement
660 * @since 2.4
661 */
662 public static IRequirement createRequirement(String namespace, IFilterExpression propsFilter,
663 IMatchExpression<IInstallableUnit> envFilter, int minCard, int maxCard, boolean greedy,
664 String description) {
665 return new RequiredPropertiesMatch(namespace, propsFilter, envFilter, minCard, maxCard, greedy, description);
666 }
667
668 /**
669 * Create and return a new requirement ({@link IRequirement}) with the specified
670 * values.
671 *
672 * @param requirement the match expression
673 * @param envFilter The filter used to evaluate whether this capability is
674 * applicable in the current environment, or
675 * <code>null</code> to indicate this capability is always
676 * applicable
677 * @param minCard minimum cardinality
678 * @param maxCard maximum cardinality
679 * @param greedy <code>true</code> if the requirement should be considered
680 * greedy and <code>false</code> otherwise
681 * @return the requirement
682 */
683 public static IRequirement createRequirement(IMatchExpression<IInstallableUnit> requirement,
684 IMatchExpression<IInstallableUnit> envFilter, int minCard, int maxCard, boolean greedy) {
685 return createRequirementInternal(requirement, envFilter, minCard, maxCard, greedy, null);
686 }
687
688 /**
689 * Create and return a new requirement ({@link IRequirement}) with the specified
690 * values.
691 *
692 * @param requirement the match expression
693 * @param envFilter the filter, or <code>null</code>
694 * @param minCard minimum cardinality
695 * @param maxCard maximum cardinality
696 * @param greedy <code>true</code> if the requirement should be considered
697 * greedy and <code>false</code> otherwise
698 * @param description a <code>String</code> description of the requirement, or
699 * <code>null</code>
700 * @return the requirement
701 */
702 public static IRequirement createRequirement(IMatchExpression<IInstallableUnit> requirement,
703 IMatchExpression<IInstallableUnit> envFilter, int minCard, int maxCard, boolean greedy,
704 String description) {
705 return createRequirementInternal(requirement, envFilter, minCard, maxCard, greedy, description);
706 }
707
708 /**
709 * Returns a new requirement change.
710 *
711 * @param applyOn The source of the requirement change - the kind of
712 * requirement to apply the change to
713 * @param newValue The result of the requirement change - the requirement to
714 * replace the source requirement with
715 * @return a requirement change
716 */
717 public static IRequirementChange createRequirementChange(IRequirement applyOn, IRequirement newValue) {
718 if ((applyOn == null || applyOn instanceof IRequiredCapability)
719 && (newValue == null || newValue instanceof IRequiredCapability))
720 return new RequirementChange((IRequiredCapability) applyOn, (IRequiredCapability) newValue);
721 throw new IllegalArgumentException();
722 }
723
724 /**
725 * Returns a new {@link ICopyright}.
726 *
727 * @param location the location of a document containing the copyright notice,
728 * or <code>null</code>
729 * @param body the copyright body, cannot be <code>null</code>
730 * @throws IllegalArgumentException when the <code>body</code> is
731 * <code>null</code>
732 */
733 public static ICopyright createCopyright(URI location, String body) {
734 return new Copyright(location, body);
735 }
736
737 /**
738 * Return a new {@link ILicense} The body should contain either the full text of
739 * the license or an summary for a license fully specified in the given
740 * location.
741 *
742 * @param location the location of a document containing the full license, or
743 * <code>null</code>
744 * @param body the license body, cannot be <code>null</code>
745 * @throws IllegalArgumentException when the <code>body</code> is
746 * <code>null</code>
747 */
748 public static ILicense createLicense(URI location, String body) {
749 return new License(location, body, null);
750 }
751
752 /**
753 * Returns an {@link IInstallableUnit} that represents the given unit bound to
754 * the given fragments.
755 *
756 * @see IInstallableUnit#isResolved()
757 * @param unit The unit to be bound
758 * @param fragments The fragments to be bound
759 * @return A resolved installable unit
760 */
761 public static IInstallableUnit createResolvedInstallableUnit(IInstallableUnit unit,
762 IInstallableUnitFragment[] fragments) {
763 if (unit.isResolved())
764 return unit;
765 Assert.isNotNull(unit);
766 Assert.isNotNull(fragments);
767 return new ResolvedInstallableUnit(unit, Arrays.asList(fragments));
768
769 }
770
771 /**
772 * Returns an instance of {@link ITouchpointData} with the given instructions.
773 *
774 * @param instructions The instructions for the touchpoint data.
775 * @return The created touchpoint data
776 */
777 public static ITouchpointData createTouchpointData(Map<String, ? extends Object> instructions) {
778 Assert.isNotNull(instructions);
779 // copy the map to protect against subsequent change by caller
780 if (instructions.isEmpty())
781 return EMPTY_TOUCHPOINT_DATA;
782
783 Map<String, ITouchpointInstruction> result = new LinkedHashMap<>(instructions.size());
784
785 for (Map.Entry<String, ? extends Object> entry : instructions.entrySet()) {
786 Object value = entry.getValue();
787 ITouchpointInstruction instruction;
788 if (value == null || value instanceof String)
789 instruction = createTouchpointInstruction((String) value, null);
790 else
791 instruction = (ITouchpointInstruction) value;
792 result.put(entry.getKey(), instruction);
793 }
794 return new TouchpointData(result);
795 }
796
797 /**
798 * Merge the given touchpoint instructions with a pre-existing touchpoint data
799 *
800 * @param initial - the initial ITouchpointData
801 * @param incomingInstructions - Map of ITouchpointInstructions to merge into
802 * the initial touchpoint data
803 * @return the merged ITouchpointData
804 */
805 public static ITouchpointData mergeTouchpointData(ITouchpointData initial,
806 Map<String, ITouchpointInstruction> incomingInstructions) {
807 if (incomingInstructions == null || incomingInstructions.size() == 0)
808 return initial;
809
810 Map<String, ITouchpointInstruction> resultInstructions = new HashMap<>(initial.getInstructions());
811 for (String key : incomingInstructions.keySet()) {
812 ITouchpointInstruction instruction = incomingInstructions.get(key);
813 ITouchpointInstruction existingInstruction = resultInstructions.get(key);
814
815 if (existingInstruction != null) {
816 String body = existingInstruction.getBody();
817 if (body == null || body.length() == 0)
818 body = instruction.getBody();
819 else if (instruction.getBody() != null) {
820 if (!body.endsWith(";")) //$NON-NLS-1$
821 body += ';';
822 body += instruction.getBody();
823 }
824
825 String importAttribute = existingInstruction.getImportAttribute();
826 if (importAttribute == null || importAttribute.length() == 0)
827 importAttribute = instruction.getImportAttribute();
828 else if (instruction.getImportAttribute() != null) {
829 if (!importAttribute.endsWith(",")) //$NON-NLS-1$
830 importAttribute += ',';
831 importAttribute += instruction.getBody();
832 }
833 instruction = createTouchpointInstruction(body, importAttribute);
834 }
835 resultInstructions.put(key, instruction);
836 }
837 return createTouchpointData(resultInstructions);
838 }
839
840 public static ITouchpointInstruction createTouchpointInstruction(String body, String importAttribute) {
841 return new TouchpointInstruction(body, importAttribute);
842 }
843
844 /**
845 * Returns a {@link TouchpointType} with the given id and version.
846 *
847 * @param id The touchpoint id
848 * @param version The touchpoint version
849 * @return A touchpoint type instance with the given id and version
850 */
851 public static ITouchpointType createTouchpointType(String id, Version version) {
852 Assert.isNotNull(id);
853 Assert.isNotNull(version);
854
855 if (id.equals(ITouchpointType.NONE.getId()) && version.equals(ITouchpointType.NONE.getVersion()))
856 return ITouchpointType.NONE;
857
858 synchronized (typeCache) {
859 ITouchpointType result = getCachedTouchpointType(id, version);
860 if (result != null)
861 return result;
862 result = new TouchpointType(id, version);
863 putCachedTouchpointType(result);
864 return result;
865 }
866 }
867
868 /**
869 *
870 * @param descriptors The IUs that the descriptor provides updates for.
871 * @param severity The update severity (either
872 * {@link IUpdateDescriptor#NORMAL} or
873 * {@link IUpdateDescriptor#HIGH})
874 * @param description A description of the update
875 * @param location a {@link URI} specifying the location or <code>null</code>
876 * @return A new update descriptor
877 */
878 public static IUpdateDescriptor createUpdateDescriptor(Collection<IMatchExpression<IInstallableUnit>> descriptors,
879 int severity, String description, URI location) {
880 return new UpdateDescriptor(descriptors, severity, description, location);
881 }
882
883 /**
884 * Creates a new update descriptor object.
885 *
886 * @param id The id of the installable unit that the descriptor
887 * provides updates for
888 * @param range The version range that the descriptor provides updates for
889 * @param severity The update severity (either
890 * {@link IUpdateDescriptor#NORMAL} or
891 * {@link IUpdateDescriptor#HIGH})
892 * @param description A description of the update
893 * @return A new update descriptor
894 */
895 public static IUpdateDescriptor createUpdateDescriptor(String id, VersionRange range, int severity,
896 String description) {
897 return createUpdateDescriptor(id, range, severity, description, null);
898 }
899
900 /**
901 * Create and return a new update descriptor {@link IUpdateDescriptor} with the
902 * specified values.
903 *
904 * @param id the identifiter for the update. Must not be
905 * <code>null</code>.
906 * @param range the version range. A <code>null</code> range is equivalent
907 * to {@link VersionRange#emptyRange} and matches all
908 * versions.
909 * @param severity the severity
910 * @param description a <code>String</code> description or <code>null</code>
911 * @param location a {@link URI} specifying the location or <code>null</code>
912 * @return the update descriptor
913 */
914 public static IUpdateDescriptor createUpdateDescriptor(String id, VersionRange range, int severity,
915 String description, URI location) {
916 Collection<IMatchExpression<IInstallableUnit>> descriptors = new ArrayList<>(1);
917 descriptors.add(RequiredCapability.createMatchExpressionFromRange(IInstallableUnit.NAMESPACE_IU_ID, id, range));
918 return createUpdateDescriptor(descriptors, severity, description, location);
919 }
920
921 private static IRequirement createRequirementInternal(IMatchExpression<IInstallableUnit> requirement,
922 IMatchExpression<IInstallableUnit> envFilter, int minCard, int maxCard, boolean greedy,
923 String description) {
924 // IRequiredCapability is simply a requirement with a match expression derived
925 // from a (namespace, name, version) tripet.
926 // However the xml format also requires that maxCard > 1 or it is serialized in
927 // the generic format.
928 // When parsing back from xml try to convert to an IRequiredCapability to retain
929 // the representation prior to serialization
930 if (RequiredCapability.isVersionRangeRequirement(requirement)) {
931 String namespace = RequiredCapability.extractNamespace(requirement);
932 String name = RequiredCapability.extractName(requirement);
933 VersionRange range = RequiredCapability.extractRange(requirement);
934 return new RequiredCapability(namespace, name, range, envFilter, minCard, maxCard, greedy, description);
935 }
936
937 if (RequiredPropertiesMatch.isPropertiesMatchRequirement(requirement)) {
938 String namespace = RequiredPropertiesMatch.extractNamespace(requirement);
939 IFilterExpression attrMatch = RequiredPropertiesMatch.extractPropertiesMatch(requirement);
940 return new RequiredPropertiesMatch(namespace, attrMatch, envFilter, minCard, maxCard, greedy, description);
941 }
942
943 return new Requirement(requirement, envFilter, minCard, maxCard, greedy, description);
944 }
945
946 private static ITouchpointType getCachedTouchpointType(String id, Version version) {
947 for (ITouchpointType typeCache1 : typeCache) {
948 if (typeCache1 != null && typeCache1.getId().equals(id) && typeCache1.getVersion().equals(version)) {
949 return typeCache1;
950 }
951 }
952 return null;
953 }
954
955 private static void putCachedTouchpointType(ITouchpointType result) {
956 // simple rotating buffer
957 typeCache[typeCacheOffset] = result;
958 typeCacheOffset = (typeCacheOffset + 1) % typeCache.length;
959 }
960 }