diff options
45 files changed, 1952 insertions, 54 deletions
diff --git a/src/lombok/AccessLevel.java b/src/lombok/AccessLevel.java index 37b91235..973b3c18 100644 --- a/src/lombok/AccessLevel.java +++ b/src/lombok/AccessLevel.java @@ -1,5 +1,29 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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. + */ package lombok; +/** + * Represents an AccessLevel. Used e.g. to specify the access level for generated methods and fields. + */ public enum AccessLevel { PUBLIC, MODULE, PROTECTED, PACKAGE, PRIVATE; } diff --git a/src/lombok/Cleanup.java b/src/lombok/Cleanup.java index c847e942..4c3838f2 100644 --- a/src/lombok/Cleanup.java +++ b/src/lombok/Cleanup.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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. + */ package lombok; import java.lang.annotation.ElementType; @@ -5,8 +26,57 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Ensures the variable declaration that you annotate will be cleaned up by calling its close method, regardless + * of what happens. Implemented by wrapping all statements following the local variable declaration to the + * end of your scope into a try block that, as a finally action, closes the resource. + * + * Example: + * <pre> + * public void copyFile(String in, String out) throws IOException { + * @Cleanup FileInputStream inStream = new FileInputStream(in); + * @Cleamup FileOutputStream outStream = new FileOutputStream(out); + * byte[] b = new byte[65536]; + * while (true) { + * int r = inStream.read(b); + * if (r == -1) break; + * outStream.write(b, 0, r); + * } + * } + * </pre> + * + * Will generate: + * <pre> + * public void copyFile(String in, String out) throws IOException { + * @Cleanup FileInputStream inStream = new FileInputStream(in); + * try { + * @Cleamup FileOutputStream outStream = new FileOutputStream(out); + * try { + * byte[] b = new byte[65536]; + * while (true) { + * int r = inStream.read(b); + * if (r == -1) break; + * outStream.write(b, 0, r); + * } + * } finally { + * out.close(); + * } + * } finally { + * in.close(); + * } + * } + * </pre> + * + * Note that the final close method call, if it throws an exception, will overwrite any exception thrown + * in the main body of the generated try block. You should NOT rely on this behaviour - future versions of + * lombok intend to silently swallow any exception thrown by the cleanup method <i>_IF</i> the main body + * throws an exception as well, as the earlier exception is usually far more useful. + * + * However, in java 1.6, generating the code to do this is prohibitively complicated. + */ @Target(ElementType.LOCAL_VARIABLE) @Retention(RetentionPolicy.SOURCE) public @interface Cleanup { + /** The name of the method that cleans up the resource. By default, 'close'. The method must not have any parameters. */ String cleanupMethod() default "close"; } diff --git a/src/lombok/Data.java b/src/lombok/Data.java index f9b02b52..a9a70ee7 100644 --- a/src/lombok/Data.java +++ b/src/lombok/Data.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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. + */ package lombok; import java.lang.annotation.ElementType; @@ -5,6 +26,18 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Generates getters for all fields, a useful toString method, and hashCode and equals implementations that check + * all non-transient fields. Will also generate setters for all non-final fields, as well as a constructor. + * + * If any method to be generated already exists (in name - the return type or parameters are not relevant), then + * that method will not be generated by the Data annotation. + * + * <code>toString</code>, <code>equals</code>, and <code>hashCode</code> use the deepX variants in the + * <code>java.util.Arrays</code> utility class. Therefore, if your class has arrays that contain themselves, + * these methods will just loop endlessly until the inevitable <code>StackOverflowError</code>. This behaviour + * is no different from <code>java.util.ArrayList</code>, though. + */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.SOURCE) public @interface Data { diff --git a/src/lombok/Getter.java b/src/lombok/Getter.java index d59ea672..581a252d 100644 --- a/src/lombok/Getter.java +++ b/src/lombok/Getter.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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. + */ package lombok; import java.lang.annotation.ElementType; @@ -5,8 +26,33 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Put on any field to make lombok build a standard getter. + * + * Example: + * <pre> + * private @Getter int foo; + * </pre> + * + * will generate: + * + * <pre> + * public int getFoo() { + * return this.foo; + * } + * </pre> + * + * Note that fields of type <code>boolean</code> (but not <code>java.lang.Boolean</code>) will result in an + * <code>isFoo</code> name instead of <code>getFoo</code>. + * + * If any method named <code>getFoo</code>/<code>isFoo</code> exists, regardless of return type or parameters, no method is generated, + * and instead a compiler warning is emitted. + */ @Target(ElementType.FIELD) @Retention(RetentionPolicy.SOURCE) public @interface Getter { + /** + * If you want your setter to be non-public, you can specify an alternate access level here. + */ lombok.AccessLevel value() default lombok.AccessLevel.PUBLIC; } diff --git a/src/lombok/Lombok.java b/src/lombok/Lombok.java index 10a58e5a..400bf3ea 100644 --- a/src/lombok/Lombok.java +++ b/src/lombok/Lombok.java @@ -1,5 +1,29 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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. + */ package lombok; +/** + * Useful utility methods to manipulate lombok-generated code. + */ public class Lombok { /** * Throws any throwable 'sneakily' - you don't need to catch it, nor declare that you throw it onwards. @@ -15,6 +39,11 @@ public class Lombok { * about the concept of a 'checked exception'. All this method does is hide the act of throwing a checked exception * from the java compiler. * + * Note that this method has a return type of <code>RuntimeException</code> it is advised you always call this + * method as argument to the <code>throw</code> statement to avoid compiler errors regarding no return + * statement and similar problems. This method won't of course return an actual <code>RuntimeException</code> - + * it never returns, it always throws the provided exception. + * * @param t The throwable to throw without requiring you to catch its type. * @return A dummy RuntimeException; this method never returns normally, it <em>always</em> throws an exception! */ diff --git a/src/lombok/Setter.java b/src/lombok/Setter.java index b00d4158..9774c5c6 100644 --- a/src/lombok/Setter.java +++ b/src/lombok/Setter.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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. + */ package lombok; import java.lang.annotation.ElementType; @@ -5,8 +26,30 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Put on any field to make lombok build a standard setter. + * + * Example: + * <pre> + * private @Setter int foo; + * </pre> + * + * will generate: + * + * <pre> + * public void setFoo(int foo) { + * this.foo = foo; + * } + * </pre> + * + * If any method named <code>setFoo</code> exists, regardless of return type or parameters, no method is generated, + * and instead a compiler warning is emitted. + */ @Target(ElementType.FIELD) @Retention(RetentionPolicy.SOURCE) public @interface Setter { + /** + * If you want your setter to be non-public, you can specify an alternate access level here. + */ lombok.AccessLevel value() default lombok.AccessLevel.PUBLIC; } diff --git a/src/lombok/SneakyThrows.java b/src/lombok/SneakyThrows.java index e9b31b3d..409429ea 100644 --- a/src/lombok/SneakyThrows.java +++ b/src/lombok/SneakyThrows.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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. + */ package lombok; import java.lang.annotation.ElementType; @@ -6,10 +27,42 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * DOCS: Requires lombok.jar at runtime. + * Sneaky throw will avoid javac's insistence that you either catch or throw onward any checked exceptions that + * statements in your method body declare they generate. + * + * Sneaky throw does not silently swallow, wrap into RuntimeException, or otherwise modify any exceptions of the listed + * checked exception types. The JVM does not check for the consistency of the checked exception system; javac does, + * and this annotation lets you opt out of its mechanism. + * + * You should use this annotation ONLY in the following two cases:<ol> + * <li>You are certain the listed exception can't actually ever happen, or only in vanishingly rare situations. + * You don't try to catch OutOfMemoryError on every statement either. Examples:<br> + * <code>IOException</code> in <code>ByteArrayOutputStream</code><br> + * <code>UnsupportedEncodingException</code> in new String(byteArray, "UTF-8").</li> + * <li>You know for certain the caller can handle the exception (for example, because the caller is + * an app manager that will handle all throwables that fall out of your method the same way), but due + * to interface restrictions you can't just add these exceptions to your 'throws' clause. + * + * Note that, as SneakyThrow is an implementation detail and <i>NOT</i> part of your method signature, it is + * a compile time error if none of the statements in your method body can throw a listed exception. + * + * <b><i>WARNING: </b></i>You must have lombok.jar available at the runtime of your app if you use SneakyThrows, + * because your code is rewritten to use {@link Lombok.sneakyThrow(Throwable)}. + * + * + * Example: + * <pre> + * @SneakyThrows(UnsupportedEncodingException.class) + * public void utf8ToString(byte[] bytes) { + * return new String(bytes, "UTF-8"); + * } + * </pre> + * + * @see Lombok.sneakyThrow(Throwable) */ @Target({ElementType.METHOD, ElementType.CONSTRUCTOR}) @Retention(RetentionPolicy.SOURCE) public @interface SneakyThrows { + /** The exception type(s) you want to sneakily throw onward. */ Class<? extends Throwable>[] value(); } diff --git a/src/lombok/Synchronized.java b/src/lombok/Synchronized.java index 0c813eb7..655f95e4 100644 --- a/src/lombok/Synchronized.java +++ b/src/lombok/Synchronized.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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. + */ package lombok; import java.lang.annotation.ElementType; @@ -5,8 +26,21 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Almost exactly like putting the 'synchronized' keyword on a method, except will synchronize on a private internal + * Object, so that other code not under your control doesn't meddle with your thread management by locking on + * your own instance. + * + * For non-static methods, a field named <code>$lock</code> is used, and for static methods, + * <code>$LOCK</code> is used. These will be generated if needed and if they aren't already present. The contents + * of the fields will be serializable. + */ @Target(ElementType.METHOD) @Retention(RetentionPolicy.SOURCE) public @interface Synchronized { + /** + * Optional: specify the name of a different field to lock on. It is a compile time error if this field + * doesn't already exist (the fields are automatically generated only if you don't specify a specific name. + */ String value() default ""; } diff --git a/src/lombok/core/AST.java b/src/lombok/core/AST.java index 24e128b2..ef752d1a 100644 --- a/src/lombok/core/AST.java +++ b/src/lombok/core/AST.java @@ -1,3 +1,24 @@ +/* + * Copyright © 2009 Reinier Zwitserloot and Roel Spilker. + * + * 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. + */ package lombok.core; import static lombok.Lombok.sneakyThrow; @@ -14,7 +35,15 @@ import java.util.IdentityHashMap; import java.util.List; import java.util.Map; +/** + * Lombok wraps the AST produced by a target platform into its own AST system, mostly because both eclipse and javac + * do not allow upward traversal (from a method to its owning type, for example). + * + * @param N The common type of all AST nodes in the internal representation of the target platform. + * For example, JCTree for javac, and ASTNode for eclipse. + */ public abstract class AST<N> { + /** The kind of node represented by a given AST.Node object. */ public enum Kind { COMPILATION_UNIT, TYPE, FIELD, INITIALIZER, METHOD, ANNOTATION, ARGUMENT, LOCAL, STATEMENT; } @@ -28,29 +57,52 @@ public abstract class AST<N> { this.fileName = fileName == null ? "(unknown).java" : fileName; } + /** Set the node object that wraps the internal Compilation Unit node. */ protected void setTop(Node top) { this.top = top; } + /** + * Return the content of the package declaration on this AST's top (Compilation Unit) node. + * + * Example: "java.util". + */ public abstract String getPackageDeclaration(); + /** + * Return the contents of each non-static import statement on this AST's top (Compilation Unit) node. + * + * Example: "java.util.IOException". + */ public abstract Collection<String> getImportStatements(); - protected <T extends Node> T putInMap(T parent) |