001package org.apache.maven.model.building;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.net.URI;
023
024/**
025 * Provides access to the contents of a POM independently of the backing store (e.g. file system, database, memory).
026 * <p>
027 * Unlike {@link ModelSource}, this interface supports loading of parent POM(s) from the same backing store and allows
028 * construction of MavenProject instances without the need to have parent POM(s) available from local or remote
029 * repositories.
030 * <p>
031 * ModelSource2 instances are cached in {@link ModelBuildingRequest#getModelCache()}. Implementations must guarantee
032 * that the connection to the backing store remains active until request's {@link ModelCache} is discarded or flushed.
033 */
034public interface ModelSource2
035    extends ModelSource
036{
037    /**
038     * Returns model source identified by a path relative to this model source POM. Implementation <strong>MUST</strong>
039     * be able to accept <code>relPath</code> parameter values that
040     * <ul>
041     * <li>use either / or \ file path separator</li>
042     * <li>have .. parent directory references</li>
043     * <li>point either at file or directory, in the latter case POM file name 'pom.xml' needs to be used by the
044     * requested model source.</li>
045     * </ul>
046     * 
047     * @param relPath is the path of the requested model source relative to this model source POM.
048     * @return related model source or <code>null</code> if no such model source.
049     */
050    ModelSource2 getRelatedSource( String relPath );
051
052    /**
053     * Returns location of the POM, never <code>null</code>.
054     */
055    URI getLocationURI();
056}