You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@creadur.apache.org by rd...@apache.org on 2012/08/18 20:05:17 UTC
svn commit: r1374624 - in
/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app:
AbstractEngine.java Act.java Result.java ResultWriterFactory.java
StreamableResource.java Whisker.java package-info.java
Author: rdonkin
Date: Sat Aug 18 18:05:16 2012
New Revision: 1374624
URL: http://svn.apache.org/viewvc?rev=1374624&view=rev
Log:
Improved javadocs based on checkstyle
Added:
creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/package-info.java (with props)
Modified:
creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/AbstractEngine.java
creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Act.java
creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Result.java
creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/ResultWriterFactory.java
creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/StreamableResource.java
creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Whisker.java
Modified: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/AbstractEngine.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/AbstractEngine.java?rev=1374624&r1=1374623&r2=1374624&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/AbstractEngine.java (original)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/AbstractEngine.java Sat Aug 18 18:05:16 2012
@@ -14,7 +14,7 @@
* "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.
+ * under the License.
*/
package org.apache.creadur.whisker.app;
@@ -25,19 +25,49 @@ import org.apache.creadur.whisker.model.
import org.apache.creadur.whisker.scan.Directory;
/**
- *
+ * A pluggable template.
*/
public abstract class AbstractEngine {
- public abstract AbstractEngine generateTemplate(Collection<Directory> withBase,
+ /**
+ * Writes templates to help create meta-data.
+ * @param withBase from this base, not null
+ * @param writerFactory not null
+ * @return this
+ * @throws Exception when creation fails
+ */
+ public abstract AbstractEngine generateTemplate(
+ Collection<Directory> withBase,
ResultWriterFactory writerFactory) throws Exception;
- public abstract AbstractEngine validate(LicenseAnalyst analyst,
+ /**
+ * Reports validations.
+ * @param analyst not null
+ * @param writerFactory not null
+ * @return not null
+ * @throws Exception when report creation fails
+ */
+ public abstract AbstractEngine validate(LicenseAnalyst analyst,
ResultWriterFactory writerFactory) throws Exception;
- public abstract AbstractEngine report(final Collection<Directory> directories,
+ /**
+ * Writes a report describing the directories present.
+ * @param directories not null
+ * @param writerFactory not null
+ * @return this
+ * @throws Exception when report creation fails
+ */
+ public abstract AbstractEngine report(
+ final Collection<Directory> directories,
ResultWriterFactory writerFactory) throws Exception;
-
- public abstract AbstractEngine generate(final Descriptor work,
+
+ /**
+ * Writes legal documents.
+ * @param work not null
+ * @param writerFactory not null
+ * @return this
+ * @throws Exception when report creation fails
+ */
+ public abstract AbstractEngine generate(final Descriptor work,
ResultWriterFactory writerFactory) throws Exception;
}
Modified: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Act.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Act.java?rev=1374624&r1=1374623&r2=1374624&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Act.java (original)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Act.java Sat Aug 18 18:05:16 2012
@@ -14,26 +14,41 @@
* "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.
+ * under the License.
*/
package org.apache.creadur.whisker.app;
/**
- *
+ * An operation to be performed by Whisker.
*/
public enum Act {
-
+
+ /** Generate legal documentation. */
GENERATE(false),
+ /** Validate contents against meta-data. */
AUDIT(true),
+ /** Writes report on directories. */
REPORT(true),
+ /** Outlines the directory structure. */
TEMPLATE(true);
+ /** Is the source required to perform this operation? */
private final boolean isSourceRequired;
- private Act(boolean isSourceRequired) {
+ /**
+ * Constructs an instance.
+ * @param isSourceRequired true when source is require,
+ * false otherwise
+ */
+ private Act(final boolean isSourceRequired) {
this.isSourceRequired = isSourceRequired;
}
+ /**
+ * Is source required for this operation?
+ * @return true when the source is required,
+ * false otherwise
+ */
public boolean isSourceRequired() {
return isSourceRequired;
}
Modified: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Result.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Result.java?rev=1374624&r1=1374623&r2=1374624&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Result.java (original)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Result.java Sat Aug 18 18:05:16 2012
@@ -14,25 +14,35 @@
* "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.
+ * under the License.
*/
package org.apache.creadur.whisker.app;
import java.io.File;
/**
- *
+ * Names results which might be produced by Whisker.
*/
public enum Result {
- LICENSE("LICENSE"), NOTICE("NOTICE"),
- MISSING_LICENSE_REPORT("missing-licenses.txt"),
- XML_TEMPLATE("manifest-template.xml"),
+ /** Software license. */
+ LICENSE("LICENSE"),
+ /** Software notice. */
+ NOTICE("NOTICE"),
+ /** Describes missing meta-data. */
+ MISSING_LICENSE_REPORT("missing-licenses.txt"),
+ /** Starting point for meta-data development. */
+ XML_TEMPLATE("manifest-template.xml"),
+ /** Describes the directories in the source. */
DIRECTORIES_REPORT("directories.txt");
-
- /** Conventional name for the result */
+
+ /** Conventional name for the result. */
private final String name;
- private Result(String name) {
+ /**
+ * Constructs an instance.
+ * @param name not null
+ */
+ private Result(final String name) {
this.name = name;
}
@@ -49,7 +59,7 @@ public enum Result {
* @param directory not null
* @return conventional file within directory
*/
- public File within(File directory) {
+ public File within(final File directory) {
return new File(directory, getName());
}
}
Modified: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/ResultWriterFactory.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/ResultWriterFactory.java?rev=1374624&r1=1374623&r2=1374624&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/ResultWriterFactory.java (original)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/ResultWriterFactory.java Sat Aug 18 18:05:16 2012
@@ -14,7 +14,7 @@
* "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.
+ * under the License.
*/
package org.apache.creadur.whisker.app;
@@ -22,7 +22,7 @@ import java.io.IOException;
import java.io.Writer;
/**
- * Builds writers for results.
+ * Builds writers for results.
*/
public interface ResultWriterFactory {
@@ -32,5 +32,5 @@ public interface ResultWriterFactory {
* @return not null
* @throws IOException when suitable writer cannot be constructed
*/
- public Writer writerFor(final Result result) throws IOException;
+ Writer writerFor(final Result result) throws IOException;
}
Modified: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/StreamableResource.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/StreamableResource.java?rev=1374624&r1=1374623&r2=1374624&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/StreamableResource.java (original)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/StreamableResource.java Sat Aug 18 18:05:16 2012
@@ -14,7 +14,7 @@
* "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.
+ * under the License.
*/
package org.apache.creadur.whisker.app;
@@ -27,9 +27,9 @@ import java.io.InputStream;
public abstract class StreamableResource {
/**
- * Opens the resource as a stream
- * @return not null
- * @throws IOException
+ * Opens the resource as a stream.
+ * @return open resource, not null
+ * @throws IOException when resource cannot be opened as a stream
*/
public abstract InputStream open() throws IOException;
}
Modified: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Whisker.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Whisker.java?rev=1374624&r1=1374623&r2=1374624&view=diff
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Whisker.java (original)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/Whisker.java Sat Aug 18 18:05:16 2012
@@ -14,13 +14,12 @@
* "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.
+ * under the License.
*/
package org.apache.creadur.whisker.app;
import java.io.IOException;
import java.io.InputStream;
-import java.io.Writer;
import java.util.Collection;
import org.apache.creadur.whisker.app.analysis.LicenseAnalyst;
@@ -31,30 +30,35 @@ import org.apache.creadur.whisker.scan.F
/**
- *
+ * High level application, configured as a bean.
*/
public class Whisker {
-
+
+ /** Operation to be performed. */
private Act act;
+ /** The source on which the operation is to be performed. */
private String source;
+ /** The meta-data. */
private StreamableResource licenseDescriptor;
+ /** Pluggable report writer. */
private ResultWriterFactory writerFactory;
-
+ /** Pluggable templating. */
private AbstractEngine engine;
/**
* Gets the factory that builds product {@link Writer}s.
* @return factory
*/
- public ResultWriterFactory getWriterFactory() {
+ public final ResultWriterFactory getWriterFactory() {
return writerFactory;
}
/**
* Sets the factory that builds product {@link Writer}s.
* @param writerFactory not null
+ * @return this, not null
*/
- public Whisker setWriterFactory(ResultWriterFactory writerFactory) {
+ public final Whisker setWriterFactory(final ResultWriterFactory writerFactory) {
this.writerFactory = writerFactory;
return this;
}
@@ -63,7 +67,7 @@ public class Whisker {
* Gets the reporting engine.
* @return not null
*/
- public AbstractEngine getEngine() {
+ public final AbstractEngine getEngine() {
return engine;
}
@@ -72,22 +76,25 @@ public class Whisker {
* @param engine not null
* @return this, not null
*/
- public Whisker setEngine(AbstractEngine engine) {
+ public final Whisker setEngine(final AbstractEngine engine) {
this.engine = engine;
return this;
}
/**
- * @return the base
+ * Gets the source on which the operation will be performed.
+ * @return the base, not null
*/
- public String getSource() {
+ public final String getSource() {
return source;
}
/**
+ * Sets the source
* @param source the base to set
+ * @return this, not null
*/
- public Whisker setSource(String source) {
+ public final Whisker setSource(final String source) {
this.source = source;
return this;
}
@@ -95,33 +102,43 @@ public class Whisker {
/**
* @return the licenseDescriptor
*/
- public StreamableResource getLicenseDescriptor() {
+ public final StreamableResource getLicenseDescriptor() {
return licenseDescriptor;
}
/**
+ * Sets meta-data describing the source licensing.
* @param licenseDescriptor the licenseDescriptor to set
+ * @return this, not null
*/
- public Whisker setLicenseDescriptor(StreamableResource licenseDescriptor) {
+ public final Whisker setLicenseDescriptor(StreamableResource licenseDescriptor) {
this.licenseDescriptor = licenseDescriptor;
return this;
}
/**
+ * Gets the operation to be performed.
* @return the act
*/
- public Act getAct() {
+ public final Act getAct() {
return act;
}
/**
+ * Sets the operation to be performed.
* @param act the act to set
+ * @return this, not null
*/
- public Whisker setAct(Act act) {
+ public final Whisker setAct(Act act) {
this.act = act;
return this;
}
-
+
+ /**
+ * Performs the operation set.
+ * @return this, not null
+ * @throws Exception when the operation fails
+ */
public Whisker act() throws Exception {
switch (act) {
case REPORT:
@@ -135,12 +152,11 @@ public class Whisker {
return generate();
}
}
-
-
-
+
/**
- * @return
- * @throws Exception
+ * Creates a template to help create meta-data.
+ * @throws Exception when the report creation fails
+ * @return this, not null
*/
private Whisker template() throws Exception {
engine.generateTemplate(directories(), getWriterFactory());
@@ -148,16 +164,19 @@ public class Whisker {
}
/**
- * @return
+ * Writes a report on the directories in the source.
+ * @return this, not null
+ * @throws Exception when the report creation fails
*/
private Whisker report() throws Exception {
engine.report(directories(), getWriterFactory());
return this;
}
-
+
/**
- * @return
- * @throws Exception
+ * Generates legal documentation.
+ * @return this, not null
+ * @throws Exception when the generation fails
*/
private Whisker generate() throws Exception {
engine.generate(new LicenseAnalyst().validate(load(getLicenseDescriptor())), getWriterFactory());
@@ -165,8 +184,9 @@ public class Whisker {
}
/**
- * @return
- * @throws Exception
+ * Writes a validation report.
+ * @return this, not null
+ * @throws Exception when the validation fails
*/
private Whisker validate() throws Exception {
engine.validate(new LicenseAnalyst(directories()).analyse(load(getLicenseDescriptor())), getWriterFactory());
@@ -174,35 +194,41 @@ public class Whisker {
}
/**
- * @return
- * @throws IOException
+ * Describes the directories within the source.
+ * @return not null
+ * @throws IOException when reading the source fails
*/
private Collection<Directory> directories() throws IOException {
return new FromFileSystem().withBase(getSource());
}
+ /**
+ * Describes the state suitable for logging.
+ * @return something suitable for logging
+ */
@Override
public String toString() {
return "Whisker [act=" + act + ", base=" + source
+ ", licenseDescriptor=" + licenseDescriptor + "]";
}
-
+
/**
- * @param resource
- * @return
- * @throws IOException
+ * Opens a resource as a stream.
+ * @param resource not null
+ * @return not null
+ * @throws IOException
*/
private InputStream resourceAsStream(final StreamableResource resource) throws IOException {
return resource.open();
}
-
-
+
+
/**
- * @param resource
- * @return
- * @throws JDOMException
- * @throws IOException
+ * Reads meta-data from the given source.
+ * @param resource not null
+ * @return not null
+ * @throws Exception when meta-data cannot be loaded
*/
private Descriptor load(final StreamableResource resource) throws Exception {
final InputStream resourceAsStream = resourceAsStream(resource);
Added: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/package-info.java
URL: http://svn.apache.org/viewvc/creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/package-info.java?rev=1374624&view=auto
==============================================================================
--- creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/package-info.java (added)
+++ creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/package-info.java Sat Aug 18 18:05:16 2012
@@ -0,0 +1,22 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.
+ */
+/**
+ * High level application components.
+ */
+package org.apache.creadur.whisker.app;
Propchange: creadur/whisker/trunk/apache-whisker-app/src/main/java/org/apache/creadur/whisker/app/package-info.java
------------------------------------------------------------------------------
svn:eol-style = native