1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.maven.api.services;
20
21 import java.io.Closeable;
22 import java.net.URI;
23 import java.nio.charset.Charset;
24 import java.nio.charset.StandardCharsets;
25 import java.nio.file.Path;
26 import java.util.Optional;
27 import org.apache.maven.api.RemoteRepository;
28 import org.apache.maven.api.annotations.Consumer;
29 import org.apache.maven.api.annotations.Experimental;
30 import org.apache.maven.api.annotations.Nonnull;
31
32 /**
33 * Transport for specified remote repository (using provided remote repository base URI as root). Must be treated as a
34 * resource, best in try-with-resource block.
35 *
36 * @since 4.0
37 */
38 @Experimental
39 @Consumer
40 public interface Transport extends Closeable {
41 /**
42 * GETs the source URI content into target (does not have to exist, or will be overwritten if exist). The
43 * source MUST BE relative from the {@link RemoteRepository#getUrl()} root.
44 *
45 * @return {@code true} if operation succeeded, {@code false} if source does not exist.
46 * @throws RuntimeException If failed (and not due source not exists).
47 */
48 boolean get(@Nonnull URI relativeSource, @Nonnull Path target);
49
50 /**
51 * GETs the source URI content as byte array. The source MUST BE relative from the {@link RemoteRepository#getUrl()}
52 * root.
53 *
54 * @return the byte array if operation succeeded, {@code null} if source does not exist.
55 * @throws RuntimeException If failed (and not due source not exists).
56 */
57 @Nonnull
58 Optional<byte[]> getBytes(@Nonnull URI relativeSource);
59
60 /**
61 * GETs the source URI content as string. The source MUST BE relative from the {@link RemoteRepository#getUrl()}
62 * root.
63 *
64 * @return the string if operation succeeded, {@code null} if source does not exist.
65 * @throws RuntimeException If failed (and not due source not exists).
66 */
67 @Nonnull
68 Optional<String> getString(@Nonnull URI relativeSource, @Nonnull Charset charset);
69
70 /**
71 * GETs the source URI content as string using UTF8 charset. The source MUST BE relative from the
72 * {@link RemoteRepository#getUrl()} root.
73 *
74 * @return the string if operation succeeded, {@code null} if source does not exist.
75 * @throws RuntimeException If failed (and not due source not exists).
76 */
77 @Nonnull
78 default Optional<String> getString(@Nonnull URI relativeSource) {
79 return getString(relativeSource, StandardCharsets.UTF_8);
80 }
81
82 /**
83 * PUTs the source file (must exist as file) to target URI. The target MUST BE relative from the
84 * {@link RemoteRepository#getUrl()} root.
85 *
86 * @throws RuntimeException If PUT fails for any reason.
87 */
88 void put(@Nonnull Path source, @Nonnull URI relativeTarget);
89
90 /**
91 * PUTs the source byte array to target URI. The target MUST BE relative from the
92 * {@link RemoteRepository#getUrl()} root.
93 *
94 * @throws RuntimeException If PUT fails for any reason.
95 */
96 void putBytes(@Nonnull byte[] source, @Nonnull URI relativeTarget);
97
98 /**
99 * PUTs the source string to target URI. The target MUST BE relative from the
100 * {@link RemoteRepository#getUrl()} root.
101 *
102 * @throws RuntimeException If PUT fails for any reason.
103 */
104 void putString(@Nonnull String source, @Nonnull Charset charset, @Nonnull URI relativeTarget);
105
106 /**
107 * PUTs the source string using UTF8 charset to target URI. The target MUST BE relative from the
108 * {@link RemoteRepository#getUrl()} root.
109 *
110 * @throws RuntimeException If PUT fails for any reason.
111 */
112 default void putString(@Nonnull String source, @Nonnull URI relativeTarget) {
113 putString(source, StandardCharsets.UTF_8, relativeTarget);
114 }
115 }