001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. 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 implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: *
017: */
018: package org.apache.ivy.plugins.repository;
019:
020: import java.io.File;
021: import java.io.IOException;
022: import java.util.List;
023:
024: import org.apache.ivy.core.module.descriptor.Artifact;
025:
026: /**
027: * Represents a collection of resources available to Ivy. Ivy uses one or more repositories as both
028: * a source of resources for Ivy enabled build systems and as a distribution center for resources
029: * generated by Ivy enabled build systems.
030: * </p>
031: * <p>
032: * A repository supports the following fundamental operations
033: * <ul>
034: * <li>retrieving a resource from the repository.</li>
035: * <li>transfering a resource to the repository.</li>
036: * <li>retrieving a listing of resources.</li>
037: * </ul>
038: * </p>
039: * <h4>Resource Retrieval</h4>
040: * </p>
041: * <p>
042: * {@link #get} retrieves a resource specified by a provided identifier creating a new file .
043: * </p>
044: * </p>
045: * <h4>resource Publication</h4>
046: * </p>
047: * <p>
048: * {@link #put} transfers a file to the repository.
049: * </p>
050: * </p>
051: * <h4>resource Listing</h4>
052: * </p>
053: * <p>
054: * {@link #list} returns a listing of file like objects belonging to a specified parent directory.
055: * </p>
056: * </p>
057: */
058: public interface Repository {
059:
060: /**
061: * Return the resource associated with a specified identifier. If the resource does not exist,
062: * it should return a Resource with exists() returning false. An IOException should only be
063: * thrown when a real IO problem occurs, like the impossibility to connect to a server.
064: *
065: * @param source
066: * A string identifying the resource.
067: * @return The resource associated with the resource identifier.
068: * @throws IOException
069: * On error whle trying to get resource.
070: */
071: Resource getResource(String source) throws IOException;
072:
073: /**
074: * Fetch a resource from the repository.
075: *
076: * @param source
077: * A string identifying the resource to be fetched.
078: * @param destination
079: * Where to place the fetched resource.
080: * @throws IOException
081: * On retrieval failure.
082: */
083: void get(String source, File destination) throws IOException;
084:
085: /**
086: * Transfer a resource to the repository
087: *
088: * @param artifact
089: * The artifact to be transferred.
090: * @param source
091: * The local file to be transferred.
092: * @param destination
093: * Where to transfer the resource.
094: * @param overwrite
095: * Whether the transfer should overwrite an existing resource.
096: * @throws IOException
097: * On publication failure.
098: */
099: void put(Artifact artifact, File source, String destination,
100: boolean overwrite) throws IOException;
101:
102: /**
103: * Return a listing of resources names
104: *
105: * @param parent
106: * The parent directory from which to generate the listing.
107: * @return A listing of the parent directory's file content, as a List of String.
108: * @throws IOException
109: * On listing failure.
110: */
111: List list(String parent) throws IOException;
112:
113: /**
114: * Add a listener to the repository.
115: *
116: * @param listener
117: * The listener to attach to the repository.
118: */
119: void addTransferListener(TransferListener listener);
120:
121: /**
122: * Remove a listener on the repository
123: *
124: * @param listener
125: * The listener to remove
126: */
127: void removeTransferListener(TransferListener listener);
128:
129: /**
130: * Determine if a given listener is attached to the repository.
131: *
132: * @param listener
133: * The listener being quireied
134: * @return <code>true</code> if the provided listener is attached to the repository,
135: * <code>false</code> if not.
136: */
137: boolean hasTransferListener(TransferListener listener);
138:
139: /**
140: * Get the repository's file separator string.
141: *
142: * @return The repository's file separator delimiter
143: */
144: String getFileSeparator();
145:
146: /**
147: * Normalize a string.
148: *
149: * @param source
150: * The string to normalize.
151: * @return The normalized string.
152: */
153: String standardize(String source);
154:
155: /**
156: * Return the name of the repository
157: */
158: String getName();
159: }
|