001/*
002 * Extra Bnd Repository Plugins
003 * Copyright (C) 2019-2021 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.Archive;
022import java.util.List;
023import org.apache.maven.model.Dependency;
024import org.osgi.resource.Capability;
025import org.osgi.resource.Requirement;
026import org.osgi.resource.Resource;
027
028/**
029 * A resource that is backed by a maven archive.
030 */
031public interface MavenResource {
032
033    /**
034     * Returns the archive. The archive is the only mandatory
035     * information when creating a {@link MavenResource}. The other
036     * informations that can be obtained can be made available
037     * lazily, i.e. can be loaded on demand. 
038     * <P>
039     * This implies that a {@link MavenResource} can be created 
040     * that does not exist in the backing maven repositories. 
041     * If not obvious from the context, a call to {@link #boundArchive()}
042     * can be used to verify that the resource exists.
043     *
044     * @return the archive
045     */
046    Archive archive();
047
048    /**
049     * Returns the bound archive. Implies looking up the archive in the
050     * backing repositories.
051     *
052     * @return the bound archive
053     * @throws MavenResourceException if the archive cannot obtained from a 
054     * repository
055     */
056    BoundArchive boundArchive() 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 archives 
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}