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