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.IOException;
22 import java.io.InputStream;
23 import java.nio.ByteBuffer;
24 import java.nio.file.Path;
25 import java.util.Collection;
26 import java.util.Map;
27
28 import org.apache.maven.api.Service;
29 import org.apache.maven.api.annotations.Experimental;
30 import org.apache.maven.api.annotations.Nonnull;
31
32 /**
33 * Checksum algorithms service.
34 *
35 * @since 4.0.0
36 */
37 @Experimental
38 public interface ChecksumAlgorithmService extends Service {
39
40 /**
41 * Returns immutable collection of all supported algorithm names.
42 */
43 @Nonnull
44 Collection<String> getChecksumAlgorithmNames();
45
46 /**
47 * Returns {@link ChecksumAlgorithm} for given algorithm name, or throws if algorithm not supported.
48 *
49 * @throws ChecksumAlgorithmServiceException if asked algorithm name is not supported.
50 * @throws NullPointerException if passed in name is {@code null}.
51 */
52 @Nonnull
53 ChecksumAlgorithm select(@Nonnull String algorithmName);
54
55 /**
56 * Returns a collection of {@link ChecksumAlgorithm} in same order as algorithm names are ordered, or throws if
57 * any of the algorithm name is not supported. The returned collection has equal count of elements as passed in
58 * collection of names, and if names contains duplicated elements, the returned list of algorithms will have
59 * duplicates as well.
60 *
61 * @throws ChecksumAlgorithmServiceException if any asked algorithm name is not supported.
62 * @throws NullPointerException if passed in list of names is {@code null}.
63 */
64 @Nonnull
65 Collection<ChecksumAlgorithm> select(@Nonnull Collection<String> algorithmNames);
66
67 /**
68 * Calculates checksums for specified data.
69 *
70 * @param data The content for which to calculate checksums, must not be {@code null}.
71 * @param algorithms The checksum algorithms to use, must not be {@code null}.
72 * @return The calculated checksums, indexed by algorithms, never {@code null}.
73 * @throws NullPointerException if passed in any parameter is {@code null}.
74 */
75 @Nonnull
76 Map<ChecksumAlgorithm, String> calculate(@Nonnull byte[] data, @Nonnull Collection<ChecksumAlgorithm> algorithms);
77
78 /**
79 * Calculates checksums for specified data.
80 *
81 * @param data The content for which to calculate checksums, must not be {@code null}.
82 * @param algorithms The checksum algorithms to use, must not be {@code null}.
83 * @return The calculated checksums, indexed by algorithms, never {@code null}.
84 * @throws NullPointerException if passed in any parameter is {@code null}.
85 */
86 @Nonnull
87 Map<ChecksumAlgorithm, String> calculate(
88 @Nonnull ByteBuffer data, @Nonnull Collection<ChecksumAlgorithm> algorithms);
89
90 /**
91 * Calculates checksums for specified file.
92 *
93 * @param file The file for which to calculate checksums, must not be {@code null}.
94 * @param algorithms The checksum algorithms to use, must not be {@code null}.
95 * @return The calculated checksums, indexed by algorithms, never {@code null}.
96 * @throws NullPointerException if passed in any parameter is {@code null}.
97 * @throws IOException In case of any IO problem.
98 */
99 @Nonnull
100 Map<ChecksumAlgorithm, String> calculate(@Nonnull Path file, @Nonnull Collection<ChecksumAlgorithm> algorithms)
101 throws IOException;
102
103 /**
104 * Calculates checksums for specified stream. Upon this method returns, the stream will be depleted (fully read)
105 * but not closed.
106 *
107 * @param stream The stream for which to calculate checksums, must not be {@code null}.
108 * @param algorithms The checksum algorithms to use, must not be {@code null}.
109 * @return The calculated checksums, indexed by algorithms, never {@code null}.
110 * @throws NullPointerException if passed in any parameter is {@code null}.
111 * @throws IOException In case of any IO problem.
112 */
113 @Nonnull
114 Map<ChecksumAlgorithm, String> calculate(
115 @Nonnull InputStream stream, @Nonnull Collection<ChecksumAlgorithm> algorithms) throws IOException;
116
117 /**
118 * The checksum algorithm.
119 */
120 interface ChecksumAlgorithm {
121 /**
122 * Returns the algorithm name, usually used as key, never {@code null} value. The name is a standard name of
123 * algorithm (if applicable) or any other designator that is algorithm commonly referred with. Example: "SHA-1".
124 */
125 @Nonnull
126 String getName();
127
128 /**
129 * Returns the file extension to be used for given checksum file (without leading dot), never {@code null}. The
130 * extension should be file and URL path friendly, and may differ from algorithm name.
131 * The checksum extension SHOULD NOT contain dot (".") character.
132 * Example: "sha1".
133 */
134 @Nonnull
135 String getFileExtension();
136
137 /**
138 * Each invocation of this method returns a new instance of calculator, never {@code null} value.
139 */
140 @Nonnull
141 ChecksumCalculator getCalculator();
142 }
143
144 /**
145 * The checksum calculator.
146 */
147 interface ChecksumCalculator {
148 /**
149 * Updates the checksum algorithm inner state with input.
150 *
151 * @throws NullPointerException if passed in buffer is {@code null}.
152 */
153 void update(@Nonnull ByteBuffer input);
154
155 /**
156 * Returns the algorithm end result as string, never {@code null}. After invoking this method, this instance should
157 * be discarded and not reused. For new checksum calculation you have to get new instance.
158 */
159 @Nonnull
160 String checksum();
161 }
162 }