001package org.eclipse.aether.resolution;
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 org.eclipse.aether.RepositorySystem;
023import org.eclipse.aether.RepositorySystemSession;
024import org.eclipse.aether.metadata.Metadata;
025import org.eclipse.aether.transfer.MetadataNotFoundException;
026
027/**
028 * The result of a metadata resolution request.
029 * 
030 * @see RepositorySystem#resolveMetadata(RepositorySystemSession, java.util.Collection)
031 */
032public final class MetadataResult
033{
034
035    private final MetadataRequest request;
036
037    private Exception exception;
038
039    private boolean updated;
040
041    private Metadata metadata;
042
043    /**
044     * Creates a new result for the specified request.
045     * 
046     * @param request The resolution request, must not be {@code null}.
047     */
048    public MetadataResult( MetadataRequest request )
049    {
050        if ( request == null )
051        {
052            throw new IllegalArgumentException( "metadata request has not been specified" );
053        }
054        this.request = request;
055    }
056
057    /**
058     * Gets the resolution request that was made.
059     * 
060     * @return The resolution request, never {@code null}.
061     */
062    public MetadataRequest getRequest()
063    {
064        return request;
065    }
066
067    /**
068     * Gets the resolved metadata (if any).
069     * 
070     * @return The resolved metadata or {@code null} if the resolution failed.
071     */
072    public Metadata getMetadata()
073    {
074        return metadata;
075    }
076
077    /**
078     * Sets the resolved metadata.
079     * 
080     * @param metadata The resolved metadata, may be {@code null} if the resolution failed.
081     * @return This result for chaining, never {@code null}.
082     */
083    public MetadataResult setMetadata( Metadata metadata )
084    {
085        this.metadata = metadata;
086        return this;
087    }
088
089    /**
090     * Records the specified exception while resolving the metadata.
091     * 
092     * @param exception The exception to record, may be {@code null}.
093     * @return This result for chaining, never {@code null}.
094     */
095    public MetadataResult setException( Exception exception )
096    {
097        this.exception = exception;
098        return this;
099    }
100
101    /**
102     * Gets the exception that occurred while resolving the metadata.
103     * 
104     * @return The exception that occurred or {@code null} if none.
105     */
106    public Exception getException()
107    {
108        return exception;
109    }
110
111    /**
112     * Sets the updated flag for the metadata.
113     * 
114     * @param updated {@code true} if the metadata was actually fetched from the remote repository during the
115     *            resolution, {@code false} if the metadata was resolved from a locally cached copy.
116     * @return This result for chaining, never {@code null}.
117     */
118    public MetadataResult setUpdated( boolean updated )
119    {
120        this.updated = updated;
121        return this;
122    }
123
124    /**
125     * Indicates whether the metadata was actually fetched from the remote repository or resolved from the local cache.
126     * If metadata has been locally cached during a previous resolution request and this local copy is still up-to-date
127     * according to the remote repository's update policy, no remote access is made.
128     * 
129     * @return {@code true} if the metadata was actually fetched from the remote repository during the resolution,
130     *         {@code false} if the metadata was resolved from a locally cached copy.
131     */
132    public boolean isUpdated()
133    {
134        return updated;
135    }
136
137    /**
138     * Indicates whether the requested metadata was resolved. Note that the metadata might have been successfully
139     * resolved (from the local cache) despite {@link #getException()} indicating a transfer error while trying to
140     * refetch the metadata from the remote repository.
141     * 
142     * @return {@code true} if the metadata was resolved, {@code false} otherwise.
143     * @see Metadata#getFile()
144     */
145    public boolean isResolved()
146    {
147        return getMetadata() != null && getMetadata().getFile() != null;
148    }
149
150    /**
151     * Indicates whether the requested metadata is not present in the remote repository.
152     * 
153     * @return {@code true} if the metadata is not present in the remote repository, {@code false} otherwise.
154     */
155    public boolean isMissing()
156    {
157        return getException() instanceof MetadataNotFoundException;
158    }
159
160    @Override
161    public String toString()
162    {
163        return getMetadata() + ( isUpdated() ? " (updated)" : " (cached)" );
164    }
165
166}