如何验证Javadoc中包含了所有自己抛出的运行时异常?
我在代码中抛出一组自定义运行时异常,我希望确保在所有公共方法中,我记录了可能抛出的运行时异常()以及原因。这将是非常麻烦的,因为我正在维护一个被许多项目使用的,并且我希望它是关于抛出(运行时)异常的预先和可预测的 是否有编译器选项、maven插件、Intellij插件或自定义工具可以帮助我查找丢失的如何验证Javadoc中包含了所有自己抛出的运行时异常?,java,exception,javadoc,runtimeexception,throws,Java,Exception,Javadoc,Runtimeexception,Throws,我在代码中抛出一组自定义运行时异常,我希望确保在所有公共方法中,我记录了可能抛出的运行时异常()以及原因。这将是非常麻烦的,因为我正在维护一个被许多项目使用的,并且我希望它是关于抛出(运行时)异常的预先和可预测的 是否有编译器选项、maven插件、Intellij插件或自定义工具可以帮助我查找丢失的抛出的子句?对于选中的异常很容易,如果我错过了一个,编译器就会抱怨,但是对于运行时异常,抛出和@抛出都不强制执行 我想到的一件事是暂时让我自己的所有运行时异常都检查异常(它们已经共享了一个超类),但这
抛出的子句?对于选中的异常很容易,如果我错过了一个,编译器就会抱怨,但是对于运行时异常,抛出
和@抛出
都不强制执行
我想到的一件事是暂时让我自己的所有运行时异常都检查异常(它们已经共享了一个超类),但这将是一次性的练习。每次进行更改时,我都希望验证我的代码/文档,这样我就永远不会忘记记录我的运行时异常
另一种方法是在整个代码中检查异常,并仅在公共api中将其转换为运行时:
class Foo {
// oops, throws not documented with @throws
public void publicMethod() {
try {
privateMethod1();
} catch (CheckedFooException e) {
throw new RuntimeFooException(e);
}
}
private void privateMethod1() throws CheckedFooException {
privateMethod2();
}
private void privateMethod2() throws CheckedFooException {
throw new CheckedFooException();
}
}
这种方法会迫使我在所有公共方法中考虑CheckedFooException。然后,为了检查我是否遗漏了一个文档(即@throws-runtimeooexception
),我只需在catch.*checkedfooteexception
上进行正则表达式搜索,并检查是否遗漏@throws
条目。不过,这个过程相当笨拙(而且有很多公共api都会添加try…catch语句)
答案:关于您是否应该记录(您自己抛出的)运行时异常,存在一些讨论(目前的摘要:这取决于),但就我的问题的直接答案而言,公认的答案充分回答了这一问题;我可以采用这种方法,实现我的用例,甚至用它制作一个maven插件,只要付出一些时间和努力。我为此上传了一篇文章。在理解了你的问题并研究了这个主题之后,我终于找到了我认为做这项工作最好的工具之一。有了它,您不仅可以找到您没有记录的每个抛出实例,而且还可以找到除了意外记录抛出值之外没有抛出任何东西的地方
这背后的思想是将代码解析为抽象语法树。然后在方法中查找方法和抛出语句。如果一个方法有任何throw语句,则从这些语句中提取异常名称。然后获取该方法的Javadoc。检查Javadoc中的所有@throw标记,并获取已记录的异常的名称。之后,将异常抛出与已记录的异常抛出进行比较。最后,您必须根据自己的使用情况自行解决这一问题
我用于此的工具是JavaParser。您可以在Github上找到它们。我下载了他们的最新版本。他们的网站在。他们写了一本关于这个主题的书,他们提到你可以花0美元买这本书。然而,我没有读到,因为他们的程序也有一个Javadoc版本,可以在上找到
我在下面编写了一个演示代码。这并不意味着这一准则是最终的。这只是一个例子。你必须把它修好,使它适合你的案子。我没有考虑嵌套类、嵌套方法或方法中的类中的方法。此外,示例代码仅针对类而非接口编写。但是,修改代码以使其能够处理接口是很容易的
为此,您需要下载javaParser,构建它,并在您的类路径中拥有它们的javaParser-core-3.15.1.jar或任何版本
下面是演示的代码,test.java是我编写的项目中的一个文件,但您可以使用任何文件。我还在示例代码中添加了注释
import com.github.javaparser.*;
import com.github.javaparser.ast.CompilationUnit;
import com.github.javaparser.ast.comments.*;
import com.github.javaparser.ast.stmt.*;
import com.github.javaparser.ast.body.*;
import com.github.javaparser.javadoc.*;
import java.io.IOException;
import java.nio.file.*;
import java.nio.charset.Charset;
import java.util.*;
import java.util.stream.Collectors;
class Main{
public static void main(String[] args) throws IOException {
// Set file path
Path path = Paths.get("test.java");
// Set configuration
ParserConfiguration parseConfig = new ParserConfiguration();
parseConfig.setCharacterEncoding(Charset.forName("UTF-8"));
parseConfig.setTabSize(4);
parseConfig.setLanguageLevel(ParserConfiguration.LanguageLevel.JAVA_8);
// Get the parser
JavaParser jvParser = new JavaParser(parseConfig);
// Parse the result
ParseResult<CompilationUnit> parseResult = jvParser.parse(path);
// Check for problem
if ( !parseResult.isSuccessful() ) {
System.out.print("Parsing java code fail with the following problems:");
List<Problem> problems = parseResult.getProblems();
for ( Problem problem : problems ){
System.out.println(problem.getMessage());
}
return;
}
// Get the compilationUnit
// No optional checking for Optional<CompilationUnit> due to already check above.
CompilationUnit compilationUnit = parseResult.getResult().get();
// Get Classes
List<ClassOrInterfaceDeclaration> classes = compilationUnit.findAll(ClassOrInterfaceDeclaration.class).stream()
.filter(c -> !c.isInterface())
.collect(Collectors.toList());
// Traverse through each class to get method
for ( ClassOrInterfaceDeclaration c : classes ) {
// Get methods
List<MethodDeclaration> methods = c.getMethods();
for ( MethodDeclaration method : methods ) {
// Get the body statement
Optional <BlockStmt> body = method.getBody();
// if no body continue
if ( !body.isPresent() ) continue;
// After getting the body of the method code
// Search for the throw statements.
List<ThrowStmt> throwStatements = body.get().findAll(ThrowStmt.class);
// No throw statements, skip
if ( throwStatements.size() == 0 ) continue;
// Storing name of exceptions thrown into this list.
List<String> exceptionsThrown = new ArrayList<String>();
for ( ThrowStmt stmt : throwStatements ){
// Convert the throw expression to object creation expression and get the type.
String exceptionName = stmt.getExpression().asObjectCreationExpr().getType().toString();
if ( !exceptionsThrown.contains(exceptionName) ) exceptionsThrown.add(exceptionName);
}
/*
* Debug block for up to this point
System.out.println(method.getName());
System.out.println(exceptionsThrown);
System.out.println();
*
**/
// Get The Javadoc
Optional<Javadoc> javadoc = method.getJavadoc();
// To store the throws Tags
List<JavadocBlockTag> throwTags;
// A list of thrown exception that been documented.
List<String> exceptionsDocumented = new ArrayList<String>();
if ( javadoc.isPresent() ) {
throwTags = javadoc.get()
.getBlockTags()
.stream()
.filter(t -> t.getType() == JavadocBlockTag.Type.THROWS)
.collect(Collectors.toList());
for ( JavadocBlockTag tag : throwTags ) {
/*
* This may be buggy as
* the code assumed @throw exception
* to be on its own line. Therefore
* it will just take the first line as the exception name.
*/
String exceptionName = tag.getContent().toText()
.split("\n")[0]; // Use system line separator or change
// line accordingly.
if ( !exceptionsDocumented.contains(exceptionName) )
exceptionsDocumented.add(exceptionName);
}
}
// getBegin can extract the line out. But evaluating the optional would take some more code
// and is just for example so this was done like this without any checking.
System.out.println("Method: " + method.getName() + " at line " + method.getBegin());
System.out.println("Throws Exceptions: ");
System.out.println(exceptionsThrown);
System.out.println("Documented Exceptions:");
System.out.println(exceptionsDocumented);
System.out.println(System.lineSeparator() + System.lineSeparator());
}
}
}
}
*
*将有符号类型解释为无符号类型的示例方法
*在十进制字符串中,值是
*{@link IntUtil#tostringassunsigned(int)IntUtil.tostringassunsigned}
*和{@link longuutil#tostringassunsigned(long)longuutil.tostringassunsigned}。
*
*
*@作者Khang Hoang Nguyen
*
*@自1.0.0.f
**/
公共最终类Base2Util{
私有Base2Util(){};
/**
*将输入字符串解析为带符号的基2位数表示形式
*转换为整数值。
*
*@param输入
*要解析为带符号的基数为2的数字的字符串
*整数值。
*
*@返回带符号的基数2的整数整数值
*{@code input}字符串。
*
*@throws NumberFormatException
*如果{@code input}字符串包含无效的带符号
*如果{@code input}字符串包含
*小于Integer.MIN\u值的值(
*{@value java.lang.Integer#MIN_value}),
*或者如果{@code input}字符串包含一个
*大于Integer.MAX\u值的值(
*{@value java.lang.Integer#MAX_value})。
*
*@EmptyStringException
*如果{@code input}字符串为空。
*
*@自1.0.0.f
**/
公共静态最终输入(最终字符串输入){
最终整数长度=input.length();
如果(长度==0)抛出新的EmptyStringException();
final char ch1=input.charAt(0);int start;
如果(ch1='-'| | ch1=='+')){
如果(长度==1)抛出新的NumberFormatException(输入);
开始=1;
}否则{
开始=0;
}
int out=0,c;
while(start31){
如果(runlen>32)抛出新的NumberFormatException(输入);
如果(ch1!='-')thr
package host.fai.lib.faiNumber;
/*
* Copyright 2019 Khang Hoang Nguyen
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files
* (the "Software"), to deal in the Software without restriction,
* including without limitation the rights to use, copy, modify, merge,
* publish, distribute, sublicense, and/or sell copies of the Software,
* and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
**/
/**
* <p>The <code>Base2Util</code> class is a final class that provides
* static methods for converting base 2 numbering system values in
* string representation to a Java's Primitive Data Type.
*
* <p>Currently this class supports converting base 2 numbers values
* in string representation to integer int values and integer
* long values.
*
* <p>This class can parse unsigned base 2 numbers to a supported
* integer signed type as if the integer type is unsigned. However,
* some of the values must be interprete properly to get the correct
* result.
*
* <p>Example for interpreting signed value as unsigned value.
*
* <p>It is possible to store the value of 18446744073709551615L
* into a long(signed) value. However, if that value is stored into a
* signed long integer type and if we were to interprete the value
* normally, we would get a -1L value. However, if the -1L value is
* pass to LongUtil.toStringAsUnsigned, we would get
* 18446744073709551615 in string format.
*
* <p>The following example is to get to -1L. First, we assign a value
* of 9223372036854775807L to an interger long variable, multiply that
* variable to 2L, and add 1L to it.
* <pre>
* long a = 9223372036854775807L * 2L + 1L;
* System.out.println(a);
* System.out.println(LongUtil.toStringAsUnsigned(a));
* </pre>
*
* <p>Example methods for interprete signed type as unsigned type
* in a decimal strings value are
* {@link IntUtil#toStringAsUnsigned(int) IntUtil.toStringAsUnsigned}
* and {@link LongUtil#toStringAsUnsigned(long) LongUtil.toStringAsUnsigned}.
* </p>
*
* @author Khang Hoang Nguyen
*
* @since 1.0.0.f
**/
public final class Base2Util{
private Base2Util(){};
/**
* Parse the input string as signed base 2 digits representation
* into an integer int value.
*
* @param input
* A string to be parsed as signed base 2 number to an
* integer int value.
*
* @return An integer int value of the signed base 2 number
* {@code input} string.
*
* @throws NumberFormatException
* If the {@code input} string contains invalid signed
* base 2 digits, if the {@code input} string contains a
* value that is smaller than the value of Integer.MIN_VALUE(
* {@value java.lang.Integer#MIN_VALUE}),
* or if the {@code input} string contains a value that
* is larger than the value of Integer.MAX_VALUE(
* {@value java.lang.Integer#MAX_VALUE}).
*
* @throws EmptyStringException
* If the {@code input} string is empty.
*
* @since 1.0.0.f
**/
public static final int toInt(final String input){
final int length = input.length();
if ( length == 0 ) throw new EmptyStringException();
final char ch1 = input.charAt(0); int start;
if ( ch1 == '-' || ch1 == '+' ){
if ( length == 1 ) throw new NumberFormatException(input);
start = 1;
} else {
start = 0;
}
int out = 0, c;
while ( start < length && input.charAt(start) == '0' ) start++;
final int runlen = length - start;
if ( runlen > 31 ){
if ( runlen > 32 ) throw new NumberFormatException(input);
if ( ch1 != '-' ) throw new NumberFormatException(input);
if ( input.charAt(start++) != '1') throw new NumberFormatException(input);
for ( ; start < length; start++){
if ( input.charAt(start) != '0' ) throw new NumberFormatException(input);
}
return -2147483648;
}
for ( ; start < length; start++){
c = (input.charAt(start) ^ '0');
if ( c > 1 ) throw new NumberFormatException(input);
out = (out << 1) | c;
}
if ( ch1 == '-' ) return ~out + 1;
return out;
}
/**
* Parse the input string as unsigned base 2 number representation
* into an integer int value as if the integer int is an unsigned
* type. For values that need to be interpreted correctly, see the
* {@link IntUtil#toStringAsUnsigned(int) toStringAsUnsigned} method
* of the {@link IntUtil IntUtil} class.
*
* @param input
* A string to be parsed as unsigned base 2 number to an
* integer int value as if the integer int is an unsigned
* type.
*
* @return An int value that represents an unsigned integer int
* value of the unsigned base 2 number {@code input} string.
*
* @throws NumberFormatException
* If the {@code input} string contains invalid unsigned
* base 2 digits, if the {@code input} string contains a
* value that is beyond the capacity of the integer int
* data type.
*
* @throws EmptyStringException
* If the {@code input} string is empty.
*
* @since 1.0.0.f
**/
public static final int toIntAsUnsigned(final String input){
final int length = input.length();
if ( length == 0 ) throw new EmptyStringException();
int start = 0;
int out = 0, c;
while ( start < length && input.charAt(start) == '0' ) start++;
if ( length - start > 32 ) throw new NumberFormatException(input);
for ( ; start < length; start++){
c = (input.charAt(start) ^ '0');
if ( c > 1 ) throw new NumberFormatException(input);
out = (out << 1) | c;
}
return out;
}
/**
* Parse the input string as signed base 2 number representation
* into an integer long value.
*
* @param input
* A string to be parsed as signed base 2 number to an
* integer long value.
*
* @return An integer long value of the signed base 2 number
* {@code input} string.
*
* @throws NumberFormatException
* If the {@code input} string contains invalid signed
* base 2 digits, if the {@code input} string contains a
* value that is smaller than the value of Long.MIN_VALUE(
* {@value java.lang.Long#MIN_VALUE}), or if
* the {@code input} string contains a value that is larger
* than the value of Long.MAX_VALUE(
* {@value java.lang.Long#MAX_VALUE}).
*
* @throws EmptyStringException
* If the {@code input} string is empty.
*
* @since 1.0.0.f
**/
public static final long toLong(final String input){
final int length = input.length();
if ( length == 0 ) throw new EmptyStringException();
final char ch1 = input.charAt(0); int start = 0;
if ( ch1 == '-' || ch1 == '+' ){
if ( length == 1 ) throw new NumberFormatException(input);
start = 1;
}
long out = 0, c;
while ( start < length && input.charAt(start) == '0' ) start++;
final int runlen = length - start;
if ( runlen > 63 ){
if ( runlen > 64 ) throw new NumberFormatException(input);
if ( ch1 != '-' ) throw new NumberFormatException(input);
if ( input.charAt(start++) != '1') throw new NumberFormatException(input);
for ( ; start < length; start++){
if ( input.charAt(start) != '0' ) throw new NumberFormatException(input);
}
return -9223372036854775808L;
}
for ( ; start < length; start++){
c = (input.charAt(start) ^ '0');
if ( c > 1L ) throw new NumberFormatException(input);
out = (out << 1) | c;
}
if ( ch1 == '-' ) return ~out + 1L;
return out;
}
/**
* Parse the input string as unsigned base 2 number representation
* into an integer long value as if the integer long is an unsigned
* type. For values that need to be interpreted correctly, see the
* {@link LongUtil#toStringAsUnsigned(long) toStringAsUnsigned} method
* of the {@link LongUtil LongUtil} class.
*
* @param input
* A string to be parsed as unsigned base 2 number to an
* integer long value as if the integer long is an unsigned
* type.
*
* @return An integer long value represent the unsigned integer
* long value of the unsigned base 2 number {@code input}
* string.
*
* @throws NumberFormatException
* If the {@code input} string contains invalid unsigned
* base 2 digits, or if the {code input} string
* contains a value that is beyond the capacity of the
* long data type.
*
* @throws EmptyStringException
* If the {@code input} string is empty.
*
* @since 1.0.0.f
**/
public static final long toLongAsUnsigned(final String input){
final int length = input.length();
if ( length == 0 ) throw new EmptyStringException();
int start = 0;
long out = 0, c;
while ( start < length && input.charAt(start) == '0' ) start++;
if ( length - start > 64 ) throw new NumberFormatException(input);
for ( ; start < length; start++){
c = (input.charAt(start) ^ '0');
if ( c > 1L ) throw new NumberFormatException(input);
out = (out << 1) | c;
}
return out;
}
}
public class MySuperException extends RuntimeException {
}
public class MyException extends MySuperException {
}
// temporary class, only for compile time checks
// do not export this into jar
public class MySuperException extends Exception {
}