com.github.jochenw.jsgen.api.ResettableBlock Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of jsgen Show documentation

Jsgen is a Java Source Generation Framework: That means, it should be a valuable tool, if you intend to write a custom generator for Java sources. As such, it is the successor of a previous framework, called JaxMeJS (http://jaxme.sourceforge.net/JaxMeJS/docs/index.html). The predecessor came into being as a standalone project. It was incorporated into the bigger JaxMe project, when the latter was adopted by the Apache Webservices project. And it was buried as part of the bigger project, when the latter was moved to the Apache Attic (http://svn.apache.org/repos/asf/webservices/archive/jaxme/). That was fine for quite some time, because the latest released version (JaxMeJS 0.5.2) did its job quite well. Over the years, however, the Java language has evolved, and the lack of support for features like Generics, or Annotations, became a burden. Hence the Successor: Jsgen picks up, where JaxMeJS ended. It is, however, a complete rewrite with several additional features, that the author considers to be important for modern Java applications: 1. It supports Generics. 2. It supports Annotations. 3. The builder pattern has been adopted. Almost all important classes are implemented as builders. This should make writing the actual source generators much more concise, and maintainable, than it used to be before. 4. The code style is configurable. Code styles allow you to concentrate on the actual work. The resulting Jave source will look nicely formatted, anyways. As of this writing, you can select between two builtin code styles: - The default code style is basically the authors personal free style, roughly comparable to the default code style of the Eclipse Java IDE. - As an alternative, there is also a Maven code style, which is widely used in the Open Source communities. Compared to the default style, it is less concise, if not even a bit verbose. On the other hand, it is widely adopted by projects in the vicinity of {{{https://maven.apache.org}Apache Maven}}. 5. Import lists are created, and sorted, automatically.

The newest version!

/**
 * Copyright 2018 Jochen Wiedmann
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.github.jochenw.jsgen.api;

import javax.annotation.Nonnull;



/** A resettable block acts as a possibility to add code, and reserve the
 * ability to revoke that code later on. Example of use:
 *  *   Method m; // The method, to which we are adding code.
 *   Resettable Block rblock = null;
 *   try {
 *       rblock = new ResettableBlock(m.getBody();
 *       // Try adding code to rblock.
 *       rblock.commit();
 *   } catch (Throwable t) {
 *       // Adding code failed, rollback, and do something different.
 *       rblock.rollback();
 *   }
 * 
 */
public class ResettableBlock extends Block {
	private @Nonnull final Block parent;

	/** Creates a new instance. The method {@link #commit()}
	 * will add code to the given parent.
	 * @param pParent The resettable blocks parent block.
	 *   Code, which is being added to the resettable block
	 *   will not be added to the parent, until the
	 *   {@link #commit()} method is being invoked, at which
	 *   point code will be transferred from the resettable
	 *   block to the parent block.
	 */
	public ResettableBlock(@Nonnull Block pParent) {
		parent = pParent;
	}

	/** Called to move all code, which has been added to the
	 * resettable block, to the parent block.
	 * 
	 */
	public void commit() {
		parent.getContents().addAll(getContents());
	}

	/** Called to discard all code, which has been added to
	 * the resettable block.
	 */
	public void rollback() {
		getContents().clear();
	}
}