001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: *
017: */
018: package org.apache.ivy.plugins.version;
019:
020: import java.util.Comparator;
021:
022: import org.apache.ivy.core.module.descriptor.ModuleDescriptor;
023: import org.apache.ivy.core.module.id.ModuleRevisionId;
024:
025: /**
026: * This interface defines a version matcher, i.e. a class able to tell if the revision asked by a
027: * module for a dependency is dynamic (i.e. need to find all revisions to find the good one among
028: * them) and if a found revision matches the asked one. Two ways of matching are possible: - based
029: * on the module revision only (known as ModuleRevisionId) - based on the parsed module descriptor
030: * The second being much more time consuming than the first, the version matcher should tell if it
031: * needs such parsing or not using the needModuleDescriptor(ModuleRevisionId askedMrid,
032: * ModuleRevisionId foundMrid) method. Anyway, the first way is always used, and if a revision is
033: * not accepted using the first method, the module descriptor won't be parsed. Therefore if a
034: * version matcher uses only module descriptors to accept a revision or not it should always return
035: * true to needModuleDescriptor(ModuleRevisionId askedMrid, ModuleRevisionId foundMrid) and
036: * accept(ModuleRevisionId askedMrid, ModuleRevisionId foundMrid).
037: */
038: public interface VersionMatcher {
039: /**
040: * Indicates if the given asked ModuleRevisionId should be considered as dynamic for the current
041: * VersionMatcher or not.
042: *
043: * @param askedMrid
044: * the dependency module revision id as asked by a module
045: * @return true if this revision is considered as a dynamic one, false otherwise
046: */
047: public boolean isDynamic(ModuleRevisionId askedMrid);
048:
049: /**
050: * Indicates if this version matcher considers that the module revision found matches the asked
051: * one.
052: *
053: * @param askedMrid
054: * @param foundMrid
055: * @return
056: */
057: public boolean accept(ModuleRevisionId askedMrid,
058: ModuleRevisionId foundMrid);
059:
060: /**
061: * Indicates if this VersionMatcher needs module descriptors to determine if a module revision
062: * matches the asked one. Note that returning true in this method may imply big performance
063: * issues.
064: *
065: * @return
066: */
067: public boolean needModuleDescriptor(ModuleRevisionId askedMrid,
068: ModuleRevisionId foundMrid);
069:
070: /**
071: * Indicates if this version matcher considers that the module found matches the asked one. This
072: * method can be called even needModuleDescriptor(ModuleRevisionId askedMrid, ModuleRevisionId
073: * foundMrid) returns false, so it is required to implement it in any case, a usual default
074: * implementation being: return accept(askedMrid, foundMD.getResolvedModuleRevisionId());
075: *
076: * @param askedMrid
077: * @param foundMD
078: * @return
079: */
080: public boolean accept(ModuleRevisionId askedMrid,
081: ModuleDescriptor foundMD);
082:
083: /**
084: * Compares a dynamic revision (askedMrid) with a static one (foundMrid) to indicate which one
085: * should be considered the greater. If there is not enough information to know which one is the
086: * greater, the dynamic one should be considered greater and this method should return 0. This
087: * method should never be called with a askdeMrid for which isDynamic returns false.
088: *
089: * @param askedMrid
090: * the dynamic revision to compare
091: * @param foundMrid
092: * the static revision to compare
093: * @param staticComparator
094: * a comparator which can be used to compare static revisions
095: * @return 0 if it's not possible to know which one is greater, greater than 0 if askedMrid
096: * should be considered greater, lower than 0 if it can't be consider greater
097: */
098: public int compare(ModuleRevisionId askedMrid,
099: ModuleRevisionId foundMrid, Comparator staticComparator);
100:
101: /**
102: * Returns the version matcher name identifying this version matcher
103: *
104: * @return the version matcher name identifying this version matcher
105: */
106: public String getName();
107: }
|