source.dussan.org Git - archiva.git/blob

   1 package org.apache.archiva.repository.storage;
   2
   3 /*
   4  * Licensed to the Apache Software Foundation (ASF) under one
   5  * or more contributor license agreements.  See the NOTICE file
   6  * distributed with this work for additional information
   7  * regarding copyright ownership.  The ASF licenses this file
   8  * to you under the Apache License, Version 2.0 (the
   9  * "License"); you may not use this file except in compliance
  10  * with the License.  You may obtain a copy of the License at
  11  *
  12  *  http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  * KIND, either express or implied.  See the License for the
  18  * specific language governing permissions and limitations
  19  * under the License.
  20  */
  21
  22 import java.io.IOException;
  23 import java.io.InputStream;
  24 import java.io.OutputStream;
  25 import java.nio.channels.ReadableByteChannel;
  26 import java.nio.channels.WritableByteChannel;
  27 import java.nio.file.Path;
  28 import java.time.Instant;
  29 import java.util.List;
  30
  31 /**
  32  * A instance of this interface represents information about a specific asset in a repository.
  33  * The asset may be an real artifact, a directory, or a virtual asset.
  34  *
  35  * Each asset has a unique path relative to the repository.
  36  *
  37  * The implementation may read the data directly from the filesystem or underlying storage implementation.
  38  *
  39  * @since 3.0
  40  * @author Martin Stockhammer <martin_s@apache.org>
  41  */
  42 public interface StorageAsset
  43 {
  44
  45     /**
  46      * Returns the storage this asset belongs to.
  47      * @return
  48      */
  49     RepositoryStorage getStorage();
  50
  51     /**
  52      * Returns the complete path relative to the repository to the given asset.
  53      *
  54      * @return A path starting with '/' that uniquely identifies the asset in the repository.
  55      */
  56     String getPath();
  57
  58     /**
  59      * Returns the name of the asset. It may be just the filename.
  60      * @return the asset name
  61      */
  62     String getName();
  63
  64     /**
  65      * Returns the time of the last modification.
  66      *
  67      * @return the time instant of the last modification
  68      */
  69     Instant getModificationTime();
  70
  71     /**
  72      * Returns true, if this asset is a container type and contains further child assets.
  73      * @return <code>true</code>, if this is a container type, otherwise <code>false</code>
  74      */
  75     boolean isContainer();
  76
  77     /**
  78      * Returns true, if this asset is a leaf node and cannot contain further childs
  79      * @return <code>true</code>, if this is a leaf type, otherwise <code>false</code>
  80      */
  81     boolean isLeaf();
  82
  83     /**
  84      * List the child assets.
  85      *
  86      * @return The list of children. If there are no children and if the asset is not a container, a empty list will be returned.
  87      */
  88     List<StorageAsset> list();
  89
  90     /**
  91      * The size in bytes of the asset. If the asset does not have a size, -1 should be returned.
  92      *
  93      * @return The size if the asset has a size, otherwise -1
  94      */
  95     long getSize();
  96
  97     /**
  98      * Returns the input stream of the artifact content.
  99      * It will throw a IOException, if the stream could not be created.
 100      * Implementations should create a new stream instance for each invocation and make sure that the
 101      * stream is proper closed after usage.
 102      *
 103      * @return The InputStream representing the content of the artifact.
 104      * @throws IOException
 105      */
 106     InputStream getReadStream() throws IOException;
 107
 108     /**
 109      * Returns a NIO representation of the data.
 110      *
 111      * @return A channel to the asset data.
 112      * @throws IOException
 113      */
 114     ReadableByteChannel getReadChannel() throws IOException;
 115
 116     /**
 117      *
 118      * Returns an output stream where you can write data to the asset. The operation is not locked or synchronized.
 119      * User of this method have to make sure, that the stream is proper closed after usage.
 120      *
 121      * @param replace If true, the original data will be replaced, otherwise the data will be appended.
 122      * @return The OutputStream where the data can be written.
 123      * @throws IOException
 124      */
 125     OutputStream getWriteStream( boolean replace) throws IOException;
 126
 127     /**
 128      * Returns a NIO representation of the asset where you can write the data.
 129      *
 130      * @param replace True, if the content should be replaced by the data written to the stream.
 131      * @return The Channel for writing the data.
 132      * @throws IOException
 133      */
 134     WritableByteChannel getWriteChannel( boolean replace) throws IOException;
 135
 136     /**
 137      * Replaces the content. The implementation may do an atomic move operation, or keep a backup. If
 138      * the operation fails, the implementation should try to restore the old data, if possible.
 139      *
 140      * The original file may be deleted, if the storage was successful.
 141      *
 142      * @param newData Replaces the data by the content of the given file.
 143      */
 144     boolean replaceDataFromFile( Path newData) throws IOException;
 145
 146     /**
 147      * Returns true, if the asset exists.
 148      *
 149      * @return True, if the asset exists, otherwise false.
 150      */
 151     boolean exists();
 152
 153     /**
 154      * Creates the asset in the underlying storage, if it does not exist.
 155      */
 156     void create() throws IOException;
 157
 158     /**
 159      * Returns the real path to the asset, if it exist. Not all implementations may implement this method.
 160      * The method throws {@link UnsupportedOperationException}, if and only if {@link #isFileBased()} returns false.
 161      *
 162      * @return The filesystem path to the asset.
 163      * @throws UnsupportedOperationException If the underlying storage is not file based.
 164      */
 165     Path getFilePath() throws UnsupportedOperationException;
 166
 167     /**
 168      * Returns true, if the asset can return a file path for the given asset. If this is true, the  {@link #getFilePath()}
 169      * will not throw a {@link UnsupportedOperationException}
 170      *
 171      * @return
 172      */
 173     boolean isFileBased();
 174
 175     /**
 176      * Returns true, if there is a parent to this asset.
 177      * @return
 178      */
 179     boolean hasParent();
 180
 181     /**
 182      * Returns the parent of this asset.
 183      * @return The asset, or <code>null</code>, if it does not exist.
 184      */
 185     StorageAsset getParent();
 186
 187     /**
 188      * Returns the asset relative to the given path
 189      * @param toPath
 190      * @return
 191      */
 192     StorageAsset resolve(String toPath);
 193 }