001/*
002 * Extra Bnd Repository Plugins
003 * Copyright (C) 2019  Michael N. Lipp
004 * 
005 * This program is free software; you can redistribute it and/or modify it 
006 * under the terms of the GNU Affero General Public License as published by 
007 * the Free Software Foundation; either version 3 of the License, or 
008 * (at your option) any later version.
009 * 
010 * This program is distributed in the hope that it will be useful, but 
011 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
012 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License 
013 * for more details.
014 * 
015 * You should have received a copy of the GNU Affero General Public License along 
016 * with this program; if not, see <http://www.gnu.org/licenses/>.
017 */
018
019package de.mnl.osgi.bnd.maven;
020
021import aQute.maven.api.Revision;
022
023import java.util.List;
024
025import org.apache.maven.model.Dependency;
026import org.osgi.resource.Capability;
027import org.osgi.resource.Requirement;
028import org.osgi.resource.Resource;
029
030/**
031 * A resource that is backed by a maven revision.
032 */
033public interface MavenResource {
034
035    /**
036     * Returns the revision. The revision is the only mandatory
037     * information when creating a {@link MavenResource}. The other
038     * informations that can be obtained can be made available
039     * lazily, i.e. can be loaded on demand. 
040     * <P>
041     * This implies that a {@link MavenResource} can be created 
042     * that does not exist in the backing maven repositories. 
043     * If not obvious from the context, a call to {@link #boundRevision()}
044     * can be used to verify that the resource exists.
045     *
046     * @return the revision
047     */
048    Revision revision();
049
050    /**
051     * Returns the bound revision.
052     *
053     * @return the revision
054     * @throws MavenResourceException the maven resource exception
055     */
056    BoundRevision boundRevision() throws MavenResourceException;
057
058    /**
059     * Returns the mandatory maven compile and runtime dependencies. 
060     * Dependencies in the POM that use variables are filtered, because
061     * these variable cannot be resolved. 
062     *
063     * @return the dependencies
064     * @throws MavenResourceException the maven resource exception
065     */
066    List<Dependency> dependencies() throws MavenResourceException;
067
068    /**
069     * Gets the underlying "ordinary" resource.
070     *
071     * @return the resource
072     * @throws MavenResourceException the maven resource exception
073     */
074    Resource asResource() throws MavenResourceException;
075
076    /**
077     * Gets the capabilities from the given namespace.
078     *
079     * @param namespace the namespace
080     * @return the capabilities
081     * @throws MavenResourceException the maven resource exception
082     */
083    List<Capability> getCapabilities(String namespace)
084            throws MavenResourceException;
085
086    /**
087     * Gets the requirements from the given namespace.
088     *
089     * @param namespace the namespace
090     * @return the requirements
091     * @throws MavenResourceException the maven resource exception
092     */
093    List<Requirement> getRequirements(String namespace)
094            throws MavenResourceException;
095
096    /**
097     * Compares a {@link MavenResource} with another maven resource
098     * or a {@link Resource}.
099     * <P>
100     * Two {@link MavenResource}s are considered equal if their revisions 
101     * are equal. If a {@link MavenResource} is compared with 
102     * another {@link Resource}, equality will be checked 
103     * between {@link MavenResource#asResource()} and the other resource 
104     * (see {@link Resource#equals(Object)}). 
105     *
106     * @param obj the object to compare with
107     * @return true, if successful
108     */
109    @Override
110    boolean equals(Object obj);
111
112    /**
113     * The hash code is defined by the revision.
114     *
115     * @return the int
116     */
117    @Override
118    int hashCode();
119
120    @Override
121    String toString();
122
123}