Skip to content
Permalink
Browse files
FREEMARKER-147 Complete Maven site documentation (#16)
  • Loading branch information
sgoeschl committed Jun 30, 2020
1 parent b9105f9 commit 4c39e8ea7a000139f53105bddf3e2048ecbc2219
Showing 67 changed files with 2,014 additions and 1,820 deletions.
@@ -3,7 +3,6 @@ Apache FreeMarker Generator

For documentation or to report bugs visit: [https://freemarker.apache.org](https://freemarker.apache.org)


Regarding pull requests on Github
-----------------------------------------------------------------------------

@@ -15,7 +14,6 @@ a [Contributor License Agreement](https://www.apache.org/dev/new-committers-guid
For contributions that are judged to be non-trivial, you will be asked
to actually signing a Contributor License Agreement.


What is Apache FreeMarker Generator?
-----------------------------------------------------------------------------

@@ -28,6 +26,16 @@ Currently it can be invoked as a
* Command-line interface `freemarker-generator-cli`
* Maven plug-in `freemarker-generator-maven-plugin`

Building Apache FreeMarker Generator
-----------------------------------------------------------------------------

To create the artefacts locally run

> mvn clean install
To build the documentation site run

> mvn clean site site:stage
Licensing
-----------------------------------------------------------------------------
@@ -1,4 +1,5 @@
# Overview
Apache FreeMarker Generator Base
=============================================================================

This module provides common functionality for `freemarker-generator-cli` and `freemarker-generator-maven-plugin` such as

@@ -16,16 +16,17 @@
*/
package org.apache.freemarker.generator.base.datasource;

import org.apache.commons.io.FilenameUtils;
import org.apache.freemarker.generator.base.util.ClosableUtils;
import org.apache.freemarker.generator.base.util.StringUtils;
import org.apache.freemarker.generator.base.util.Validate;

import java.io.Closeable;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;

import static java.util.stream.Collectors.toList;
import static org.apache.commons.io.FilenameUtils.wildcardMatch;

/**
* Container for data sources with a couple of convenience functions to select
@@ -36,13 +37,14 @@ public class DataSources implements Closeable {
private final List<DataSource> dataSources;

public DataSources(Collection<DataSource> dataSources) {
Validate.notNull(dataSources, "No data sources provided");
this.dataSources = new ArrayList<>(dataSources);
}

/**
* Get the names of all data sources.
*
* @return datas ource names
* @return data source names
*/
public List<String> getNames() {
return dataSources.stream()
@@ -109,24 +111,24 @@ public DataSource get(String name) {
/**
* Find data sources based on their name and globbing pattern.
*
* @param wildcard globbing pattern
* @param wildcard the wildcard string to match against
* @return list of matching data sources
*/
public List<DataSource> find(String wildcard) {
return dataSources.stream()
.filter(d -> wildcardMatch(d.getName(), wildcard))
.filter(d -> FilenameUtils.wildcardMatch(d.getName(), wildcard))
.collect(toList());
}

/**
* Find data sources based on their group and and globbing pattern.
*
* @param wildcard globbing pattern
* @param wildcard the wildcard string to match against
* @return list of mathching data sources
*/
public List<DataSource> findByGroup(String wildcard) {
return dataSources.stream()
.filter(d -> wildcardMatch(d.getGroup(), wildcard))
.filter(d -> FilenameUtils.wildcardMatch(d.getGroup(), wildcard))
.collect(toList());
}

@@ -139,9 +141,6 @@ public void close() {
public String toString() {
return "DataSource{" +
"dataSources=" + dataSources +
", names=" + getNames() +
", groups=" + getGroups() +
", size=" + size() +
'}';
}
}
@@ -26,9 +26,11 @@
import static java.util.Objects.requireNonNull;

/**
* Information about where to write the ouput of a template. Initially we
* Information about where to write the output of a template. Initially we
* wanted to use a <code>FileWriter</code> but it requires actually an
* existing output file (otherwise a FileNotFound exception is thrown).
* An alternative could be a "LazyFileWriter" which creates the file on
* the first write access.
*/
public class TemplateOutput {

@@ -23,7 +23,7 @@

/**
* Information how to load a template. The template is either
* provided as source code or as template path resolved
* provided as literal text or as template path resolved
* by FreeMarker's template loader.
*/
public class TemplateSource {
@@ -64,17 +64,38 @@ private TemplateSource(String name, String path, Charset encoding) {
this.encoding = encoding;
}

/**
* Template will be loaded from path using a file-base template loader.
*
* @param path template path
* @return file-based template source
*/
public static TemplateSource fromPath(String path) {
Validate.notEmpty(path, "Template path is empty");
return new TemplateSource(path, path, StandardCharsets.UTF_8);
}

/**
* Template will be loaded from path using a file-base template loader.
*
* @param path template path
* @param encoding character encoding og template
* @return file-based template source
*/

public static TemplateSource fromPath(String path, Charset encoding) {
Validate.notEmpty(path, "Template path is empty");
Validate.notNull(encoding, "Template encoding is null");
return new TemplateSource(path, path, encoding);
}

/**
* Template will be loaded from a literal content.
*
* @param name name of the template
* @param code template code
* @return template source
*/
public static TemplateSource fromCode(String name, String code) {
Validate.notEmpty(name, "Template name is empty");
Validate.notEmpty(code, "Template code is empty");
@@ -22,6 +22,9 @@

import static java.util.Objects.requireNonNull;

/**
* Keeps track of all transformations being executed.
*/
public class TemplateTransformations {

private final List<TemplateTransformation> templateTransformations;
@@ -24,7 +24,7 @@
import static org.apache.freemarker.generator.base.util.StringUtils.isEmpty;

/**
* Parses the URI fragment as list of name/value pairs seperated by an ampersand.
* Parses the URI fragment as list of name/value pairs separated by an ampersand.
*/
public class UriFragmentParser {

@@ -58,7 +58,10 @@ public static <T> List<List<T>> transpose(final List<List<T>> table) {
* @return copied array
*/
public static <T> T coalesce(List<T> list) {
return list.stream().filter(Objects::nonNull).findFirst().orElseGet(() -> null);
return list.stream()
.filter(Objects::nonNull)
.findFirst()
.orElse(null);
}

/**
@@ -19,7 +19,7 @@
import java.io.File;

/**
* Simple validation methods designed for interal use.
* Simple validation methods designed for internal use.
*/
public final class Validate {

@@ -1 +1,3 @@
TBD
# Apache FreeMarker CLI Base

This package contains infrastructure code not depending on `Apache FreeMarker` directly since `DataSources` and their creation might be useful for un-related command-line tools.
@@ -90,7 +90,6 @@ public void shouldGetAllDataSource() {
assertEquals("unknown", dataSources().get(0).getName());
assertEquals("pom.xml", dataSources().get(1).getName());
assertEquals("server.invalid", dataSources().get(2).getName());
assertEquals("unknown", dataSources().getFirst().getName());
assertEquals(3, dataSources.getList().size());
assertEquals(3, dataSources.size());
assertFalse(dataSources.isEmpty());
@@ -31,9 +31,8 @@ public class TemplateSourceFactoryTest {

private static final String ANY_TEMPLATE_PATH = "any/template/path.ftl";
private static final String ANY_FILE_NAME = "pom.xml";
private static final String ANY_URL = "https://jsonplaceholder.typicode.com/posts/2";
private static final String ANY_URL = "https://raw.githubusercontent.com/apache/freemarker-generator/master/freemarker-generator-cli/templates/info.ftl";
private static final String ANY_ENVIRONMENT_VARIABLE = "env:///PWD";
private static final String ANY_NAMED_URI = "content:www=https://www.google.com?foo=bar#contenttype=application/json";

@Test
public void shouldCreateFromTemplatePath() {
@@ -66,7 +65,7 @@ public void shouldCreateFromEnvironmentVariable() {
}

@Test
@Ignore("Requires internet access")
// @Ignore("Requires internet access")
public void shouldCreateFromUrl() {
final TemplateSource templateSource = TemplateSourceFactory.create(ANY_URL);

@@ -77,11 +76,11 @@ public void shouldCreateFromUrl() {
}

@Test
@Ignore("Requires internet access")
// @Ignore("Requires internet access")
public void shouldCreateFromNamedUri() {
final TemplateSource templateSource = TemplateSourceFactory.create(ANY_NAMED_URI);
final TemplateSource templateSource = TemplateSourceFactory.create("info=" + ANY_URL);

assertNotNull(templateSource.getName());
assertEquals("info", templateSource.getName());
assertEquals(Origin.CODE, templateSource.getOrigin());
assertNull(templateSource.getPath());
assertFalse(templateSource.getCode().isEmpty());
@@ -12,7 +12,6 @@ All notable changes to this project will be documented in this file. We try to a
* [FREEMARKER-135] Support user-supplied names for `DataSource` on the command line
* [FREEMARKER-129] Support `DataSource` exclude pattern in addition to include pattern
* [FREEMARKER-129] User-defined parameters are passed as `-Pkey=value` instead of using system properties
* [FREEMARKER-129] Add `freemarker-generator-maven-plugin-sample` for better testing of the Maven plugin
* [FREEMARKER-129] Migrate `freemarker-cli` into `freemarker-generator` project (see [https://github.com/sgoeschl/freemarker-cli](https://github.com/sgoeschl/freemarker-cli))

### Changed
@@ -24,12 +23,9 @@ All notable changes to this project will be documented in this file. We try to a
* [FREEMARKER-129] Use `freemarker.configuration.setting` in `freemarker-cli.properties` to configure FreeMarker
* [FREEMARKER-129] Provide a `toString()` metheod for all tools
* [FREEMARKER-129] Use version "0.X.Y" to cater for API changes according to [Semantic Versioning](https://semver.org)
* [FREEMARKER-129] Change artifact `freemarker-maven-plugin` to `freemarker-generator-maven-plugin`
* [FREEMARKER-128] Update `freemarker-maven-plugin` to Apache FreeMarker 2.3.29

### Deleted

### Fixed
* [FREEMARKER-147] Complete Maven site documenation
* [FREEMARKER-127] Site build fails with missing "org/apache/maven/doxia/siterenderer/DocumentContent"

[FREEMARKER-127]: https://issues.apache.org/jira/browse/FREEMARKER-127
@@ -42,4 +38,5 @@ All notable changes to this project will be documented in this file. We try to a
[FREEMARKER-139]: https://issues.apache.org/jira/browse/FREEMARKER-139
[FREEMARKER-142]: https://issues.apache.org/jira/browse/FREEMARKER-142
[FREEMARKER-144]: https://issues.apache.org/jira/browse/FREEMARKER-144
[FREEMARKER-146]: https://issues.apache.org/jira/browse/FREEMARKER-146
[FREEMARKER-146]: https://issues.apache.org/jira/browse/FREEMARKER-146
[FREEMARKER-147]: https://issues.apache.org/jira/browse/FREEMARKER-147

0 comments on commit 4c39e8e

Please sign in to comment.