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