From 013fafbeae532cc759659c940ff5fcea5c3b14aa Mon Sep 17 00:00:00 2001 From: Lukas Eder Date: Fri, 17 May 2013 19:41:35 +0200 Subject: [PATCH] [#1737] Annotate API with grammar information and generate BNF pseudo-notation for the manual - Added annotations --- .../java/org/jooq/api/annotation/State.java | 76 +++++++++++++ .../org/jooq/api/annotation/Transition.java | 102 ++++++++++++++++++ 2 files changed, 178 insertions(+) create mode 100644 jOOQ/src/main/java/org/jooq/api/annotation/State.java create mode 100644 jOOQ/src/main/java/org/jooq/api/annotation/Transition.java diff --git a/jOOQ/src/main/java/org/jooq/api/annotation/State.java b/jOOQ/src/main/java/org/jooq/api/annotation/State.java new file mode 100644 index 0000000000..fec8c37e4d --- /dev/null +++ b/jOOQ/src/main/java/org/jooq/api/annotation/State.java @@ -0,0 +1,76 @@ +/** + * Copyright (c) 2009-2013, Lukas Eder, lukas.eder@gmail.com + * All rights reserved. + * + * This software is licensed to you under the Apache License, Version 2.0 + * (the "License"); You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * . Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * . Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * . Neither the name "jOOQ" nor the names of its contributors may be + * used to endorse or promote products derived from this software without + * specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ +package org.jooq.api.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Defines a "state" in the state machine modelled by the DSL API. + * + * @author Lukas Eder + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.TYPE) +public @interface State { + + /** + * The State name. + *

+ * This describes the name of a state in the state machine modelled by the + * DSL API. By default, the state name matches the type name of the + * annotated type. + */ + String name() default ""; + + /** + * The State's aliases. + *

+ * This describes the alias names of a state in the state machine modelled + * by the DSL API. + */ + String[] aliases() default ""; + + /** + * The State's level. + *

+ * This describes whether the state is considered a "terminal state", i.e. a + * state from which the state transitions can "exit". + */ + boolean terminal() default false; +} diff --git a/jOOQ/src/main/java/org/jooq/api/annotation/Transition.java b/jOOQ/src/main/java/org/jooq/api/annotation/Transition.java new file mode 100644 index 0000000000..631033745f --- /dev/null +++ b/jOOQ/src/main/java/org/jooq/api/annotation/Transition.java @@ -0,0 +1,102 @@ +/** + * Copyright (c) 2009-2013, Lukas Eder, lukas.eder@gmail.com + * All rights reserved. + * + * This software is licensed to you under the Apache License, Version 2.0 + * (the "License"); You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * . Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * . Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * . Neither the name "jOOQ" nor the names of its contributors may be + * used to endorse or promote products derived from this software without + * specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ +package org.jooq.api.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; +import java.lang.reflect.Method; + +/** + * Defines a "transition" in the state machine modelled by the DSL API. + * + * @author Lukas Eder + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +public @interface Transition { + + /** + * The Transition name. + *

+ * This describes the name of a transition in the state machine modelled by + * the DSL API. By default, the transition name matches the method name of + * the annotated method. + */ + String name() default ""; + + /** + * The Transition arguments. + *

+ * This describes the arguments of a transition in the state machine + * modelled by the DSL API. + */ + String[] args() default ""; + + /** + * The Transition source state. + *

+ * This describes the source state name of a transition in the state machine + * modelled by the DSL API. By default, the transition's source state name + * matches the state name of the declaring type of the annotated method: + *

+ */ + String from() default ""; + + /** + * The Transition target state. + *

+ * This describes the target state name of a transition in the state machine + * modelled by the DSL API. By default, the transition's target state name + * matches the state name of the return type of the annotated method: + *

+ */ + String to() default ""; +}