001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether.spi.connector;
020
021import java.io.File;
022import java.nio.file.Path;
023
024import org.eclipse.aether.metadata.Metadata;
025import org.eclipse.aether.transfer.MetadataTransferException;
026
027/**
028 * A download/upload of metadata.
029 *
030 * @noextend This class is not intended to be extended by clients.
031 */
032public abstract class MetadataTransfer extends Transfer {
033
034    private Metadata metadata;
035
036    private Path path;
037
038    private MetadataTransferException exception;
039
040    MetadataTransfer() {
041        // hide
042    }
043
044    /**
045     * Gets the metadata being transferred.
046     *
047     * @return The metadata being transferred or {@code null} if not set.
048     */
049    public Metadata getMetadata() {
050        return metadata;
051    }
052
053    /**
054     * Sets the metadata to transfer.
055     *
056     * @param metadata The metadata, may be {@code null}.
057     * @return This transfer for chaining, never {@code null}.
058     */
059    public MetadataTransfer setMetadata(Metadata metadata) {
060        this.metadata = metadata;
061        return this;
062    }
063
064    /**
065     * Gets the local file the metadata is downloaded to or uploaded from. In case of a download, a connector should
066     * first transfer the bytes to a temporary file and only overwrite the target file once the entire download is
067     * completed such that an interrupted/failed download does not corrupt the current file contents.
068     *
069     * @return The local file or {@code null} if not set.
070     * @deprecated Use {@link #getPath()} instead.
071     */
072    @Deprecated
073    public File getFile() {
074        return path != null ? path.toFile() : null;
075    }
076
077    /**
078     * Gets the local file the metadata is downloaded to or uploaded from. In case of a download, a connector should
079     * first transfer the bytes to a temporary file and only overwrite the target file once the entire download is
080     * completed such that an interrupted/failed download does not corrupt the current file contents.
081     *
082     * @return The local file or {@code null} if not set.
083     * @since 2.0.0
084     */
085    public Path getPath() {
086        return path;
087    }
088
089    /**
090     * Sets the local file the metadata is downloaded to or uploaded from.
091     *
092     * @param file The local file, may be {@code null}.
093     * @return This transfer for chaining, never {@code null}.
094     * @deprecated Use {@link #setPath(Path)} instead.
095     */
096    @Deprecated
097    public MetadataTransfer setFile(File file) {
098        return setPath(file != null ? file.toPath() : null);
099    }
100
101    /**
102     * Sets the local file the metadata is downloaded to or uploaded from.
103     *
104     * @param path The local file, may be {@code null}.
105     * @return This transfer for chaining, never {@code null}.
106     * @since 2.0.0
107     */
108    public MetadataTransfer setPath(Path path) {
109        this.path = path;
110        return this;
111    }
112
113    /**
114     * Gets the exception that occurred during the transfer (if any).
115     *
116     * @return The exception or {@code null} if the transfer was successful.
117     */
118    public MetadataTransferException getException() {
119        return exception;
120    }
121
122    /**
123     * Sets the exception that occurred during the transfer.
124     *
125     * @param exception The exception, may be {@code null} to denote a successful transfer.
126     * @return This transfer for chaining, never {@code null}.
127     */
128    public MetadataTransfer setException(MetadataTransferException exception) {
129        this.exception = exception;
130        return this;
131    }
132}