001 /*
002 * Copyright 2004-2005 Stephen J. McConnell.
003 * Copyright 2004 Niclas Hedhman.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
014 * implied.
015 *
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019
020 package net.dpml.transit;
021
022 import java.io.File;
023 import java.io.IOException;
024 import java.io.InputStream;
025 import java.io.OutputStream;
026
027 import net.dpml.transit.artifact.ArtifactAlreadyExistsException;
028
029 /**
030 * The CacheHandler interface defines the contract for classes capable of
031 * supporting the cache management aspects of a transit system. Cache management
032 * encompasses the retreval of resources based on artifact identifiers. A cache
033 * manager implementations may provide varying levels of quality-of-services.
034 * Selection of a cache manager is defined under the transit cache configuration
035 * properties.
036 *
037 * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
038 * @version 1.1.0
039 */
040 public interface CacheHandler
041 {
042 /**
043 * Return the cache directory.
044 * @param artifact the artifact to resolve
045 * @return the working cache directory
046 * @exception IOException if an IO error occurs
047 */
048 File getLocalFile( Artifact artifact ) throws IOException;
049
050 /**
051 * Initialization of the cache handler. This operation is invoked by
052 * the transit context following the establishment of bootstrap
053 * services. During initialization the implementation loads any custom
054 * resource hosts.
055 *
056 * @exception IOException if an IO error occurs
057 */
058 void initialize() throws IOException;
059
060 /**
061 * Attempts to download and cache a remote artifact using a set of remote
062 * repositories.
063 *
064 * @param artifact the artifact to retrieve and cache
065 * @return an input stream to the local resource
066 * @exception IOException if an IO error occurs
067 * @exception TransitException is a transit system error occurs
068 */
069 InputStream getResource( Artifact artifact )
070 throws IOException, TransitException;
071
072 /**
073 * Attempts to download and cache a remote artifact using a set of remote
074 * repositories.
075 * <p>
076 * This method allows an internal reference to be passed to the
077 * cache handler and it is expected to return the InputStream of the
078 * internal item inside Jar/Zip files. If this method is called, the
079 * implementation can assume that the artifact is a Zip file.
080 * </p>
081 *
082 * @param artifact the artifact to retrieve and cache
083 * @param internalReference referencing a item within the artifact. This
084 * argument may start with "!" or "!/", which should be ignored.
085 * @return a file referencing the local resource
086 * @exception IOException if an IO error occurs
087 * @exception TransitException is a transit system error occurs
088 */
089 InputStream getResource( Artifact artifact, String internalReference )
090 throws IOException, TransitException;
091
092 /** Creates an output stream to where the artifact content can be written
093 * to.
094 * <p>
095 * If the artifact already exists, a <code>ArtifactAlreadyExistsException</code>
096 * will be thrown. If the directory doesn't exists, it will be created.
097 * The CacheHandler is responsible to recognize the completion of the
098 * writes through the <code>close()</code> method in the output stream,
099 * and do any post-processing there.
100 * </p>
101 * @param artifact the artifact
102 * @return an output stream
103 * @exception NullArgumentException if the artifact argument is null.
104 * @exception ArtifactAlreadyExistsException if the artifact already exists in the cache.
105 * @exception IOException if an IO error occurs
106 */
107 OutputStream createOutputStream( Artifact artifact )
108 throws NullArgumentException, ArtifactAlreadyExistsException, IOException;
109
110 /**
111 * Return the layout used by the cache.
112 * @return the cache layout
113 */
114 Layout getLayout();
115
116 /**
117 * Return the layout registry.
118 * @return the layout registry.
119 */
120 LayoutRegistry getLayoutRegistry();
121
122 /**
123 * Return the current cache directory.
124 * @return the cache directory.
125 */
126 File getCacheDirectory();
127 }