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
28 import org.apache.maven.api.RemoteRepository;
29 import org.apache.maven.api.annotations.Consumer;
30 import org.apache.maven.api.annotations.Experimental;
31 import org.apache.maven.api.annotations.Nonnull;
32
33 /**
34 * Transport for specified remote repository (using provided remote repository base URI as root). Must be treated as a
35 * resource, best in try-with-resource block.
36 *
37 * @since 4.0.0
38 */
39 @Experimental
40 @Consumer
41 public interface Transport extends Closeable {
42 /**
43 * GETs the source URI content into target (does not have to exist, or will be overwritten if exist). The
44 * source MUST BE relative from the {@link RemoteRepository#getUrl()} root.
45 *
46 * @return {@code true} if operation succeeded, {@code false} if source does not exist.
47 * @throws RuntimeException If failed (and not due source not exists).
48 */
49 boolean get(@Nonnull URI relativeSource, @Nonnull Path target);
50
51 /**
52 * GETs the source URI content as byte array. The source MUST BE relative from the {@link RemoteRepository#getUrl()}
53 * root.
54 *
55 * @return the byte array if operation succeeded, {@code null} if source does not exist.
56 * @throws RuntimeException If failed (and not due source not exists).
57 */
58 @Nonnull
59 Optional<byte[]> getBytes(@Nonnull URI relativeSource);
60
61 /**
62 * GETs the source URI content as string. The source MUST BE relative from the {@link RemoteRepository#getUrl()}
63 * root.
64 *
65 * @return the string if operation succeeded, {@code null} if source does not exist.
66 * @throws RuntimeException If failed (and not due source not exists).
67 */
68 @Nonnull
69 Optional<String> getString(@Nonnull URI relativeSource, @Nonnull Charset charset);
70
71 /**
72 * GETs the source URI content as string using UTF8 charset. The source MUST BE relative from the
73 * {@link RemoteRepository#getUrl()} root.
74 *
75 * @return the string if operation succeeded, {@code null} if source does not exist.
76 * @throws RuntimeException If failed (and not due source not exists).
77 */
78 @Nonnull
79 default Optional<String> getString(@Nonnull URI relativeSource) {
80 return getString(relativeSource, StandardCharsets.UTF_8);
81 }
82
83 /**
84 * PUTs the source file (must exist as file) to target URI. The target MUST BE relative from the
85 * {@link RemoteRepository#getUrl()} root.
86 *
87 * @throws RuntimeException If PUT fails for any reason.
88 */
89 void put(@Nonnull Path source, @Nonnull URI relativeTarget);
90
91 /**
92 * PUTs the source byte array to target URI. The target MUST BE relative from the
93 * {@link RemoteRepository#getUrl()} root.
94 *
95 * @throws RuntimeException If PUT fails for any reason.
96 */
97 void putBytes(@Nonnull byte[] source, @Nonnull URI relativeTarget);
98
99 /**
100 * PUTs the source string to target URI. The target MUST BE relative from the
101 * {@link RemoteRepository#getUrl()} root.
102 *
103 * @throws RuntimeException If PUT fails for any reason.
104 */
105 void putString(@Nonnull String source, @Nonnull Charset charset, @Nonnull URI relativeTarget);
106
107 /**
108 * PUTs the source string using UTF8 charset to target URI. The target MUST BE relative from the
109 * {@link RemoteRepository#getUrl()} root.
110 *
111 * @throws RuntimeException If PUT fails for any reason.
112 */
113 default void putString(@Nonnull String source, @Nonnull URI relativeTarget) {
114 putString(source, StandardCharsets.UTF_8, relativeTarget);
115 }
116 }