Spring/spring-shell
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix javadoc warnings

Browse Source
This commit is contained in:
Eric Bottard
2017-08-28 18:07:24 +02:00
parent e9f3eab859
commit 79bca79af7
11 changed files with 87 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -15,3 +15,4 @@ target/
/*.iws
out
.gradletasknamecache
.DS_Store

18
src/main/java/org/springframework/shell/TerminalSizeAware.java
View File

@@ -1,9 +1,25 @@
/*
* Copyright 2017 the original author or authors.
*
* 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 org.springframework.shell;
/**
* To be implemented by command result objects that can adapt to the terminal size when they are being rendered.
*
* <p>An object which does not implement this interface will simply be rendered by invoking its {@link #toString()}
* <p>An object which does not implement this interface will simply be rendered by invoking its {@link Object#toString()}
* method.</p>
*
* @author Eric Bottard

17
src/main/java/org/springframework/shell/table/Aligner.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2015 the original author or authors.
* Copyright 2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -24,11 +24,18 @@ package org.springframework.shell.table;
public interface Aligner {
/**
* Perform text alignment, returning a String array that MUST contain
* {@code cellHeight} lines, each of which MUST be {@code cellWidth} chars in length.
* Perform text alignment, returning a String array that MUST contain {@code cellHeight}
* lines, each of which MUST be {@code cellWidth} chars in length.
*
* <p>Input array is guaranteed to contain lines that have length equal to {@cellWidth}. There
* is no guarantee on the input number of lines though.</p>
* <p>
* Input array is guaranteed to contain lines that have length equal to {@code cellWidth}.
* There is no guarantee on the input number of lines though.
* </p>
*
* @param text the text to align
* @param cellWidth the width of of the table cell
* @param cellHeight the height of the table cell
* @return the aligned text, in a {@code cellHeight} element array
*/
String[] align(String[] text, int cellWidth, int cellHeight);
}

7
src/main/java/org/springframework/shell/table/CellMatcher.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2015 the original author or authors.
* Copyright 2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -26,7 +26,10 @@ package org.springframework.shell.table;
public interface CellMatcher {
/**
* Return whether a given cell of the table should match.
* @return whether a given cell of the table should match.
* @param row the row being tested.
* @param column the column being tested
* @param model the data model of the table
*/
public boolean matches(int row, int column, TableModel model);
}

14
src/main/java/org/springframework/shell/table/CellMatchers.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2015 the original author or authors.
* Copyright 2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -24,7 +24,7 @@ package org.springframework.shell.table;
public class CellMatchers {
/**
* Return a matcher that applies to every cell of the table.
* @return a matcher that applies to every cell of the table.
*/
public static CellMatcher table() {
return new CellMatcher() {
@@ -35,7 +35,8 @@ public class CellMatchers {
}
/**
* Return a matcher that applies to every cell of some column of the table.
* @return a matcher that applies to every cell of some column of the table.
* @param col the column to select
*/
public static CellMatcher column(final int col) {
return new CellMatcher() {
@@ -46,7 +47,8 @@ public class CellMatchers {
}
/**
* Return a matcher that applies to every cell of some row of the table.
* @return a matcher that applies to every cell of some row of the table.
* @param theRow the row to select
*/
public static CellMatcher row(final int theRow) {
return new CellMatcher() {
@@ -56,6 +58,10 @@ public class CellMatchers {
};
}
/**
* @param clazz the type that cells should contain
* @return a matcher that matches cells whose content is of a certain type
*/
public static CellMatcher ofType(final Class<?> clazz) {
return new CellMatcher() {
@Override

4
src/main/java/org/springframework/shell/table/SizeConstraints.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2015 the original author or authors.
* Copyright 2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -26,7 +26,7 @@ import org.springframework.util.Assert;
public interface SizeConstraints {
/**
* Return the minimum and maximum width of the cell, given its raw content.
* @return the minimum and maximum width of the cell, given its raw content.
* @param raw the raw String representation of the cell contents (may be reformatted later, eg wrapped)
* @param tableWidth the whole available width for the table
* @param nbColumns the number of columns in the table

10
src/main/java/org/springframework/shell/table/Table.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2015 the original author or authors.
* Copyright 2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -30,14 +30,14 @@ import org.springframework.shell.TerminalSizeAware;
* TableModel, which holds raw table contents. Its rendering logic is then altered by applying
* various customizations, in a fashion very similar to what is used <i>e.g.</i> in a spreadsheet
* program:<ol>
* <li>{@link #format(CellMatcher, Formatter) formatters} know how to derive character data out of raw data. For
* <li>{@link #formatters formatters} know how to derive character data out of raw data. For
* example, numbers are
* formatted according to a Locale, or Maps are emitted as a series of {@literal key=value} lines</li>
* <li>{@link #size(CellMatcher, SizeConstraints) size constraints} are then applied, which decide how
* <li>{@link #sizeConstraints size constraints} are then applied, which decide how
* much column real estate to allocate to cells</li>
* <li>{@link #wrap(CellMatcher, TextWrapper) text wrapping policies} are applied once the column sizes
* <li>{@link #wrappers text wrapping policies} are applied once the column sizes
* are known</li>
* <li>finally, {@link #align(CellMatcher, Aligner) alignment} strategies actually render
* <li>finally, {@link #aligners alignment} strategies actually render
* text as a series of space-padded strings that draw nicely on screen.</li>
* </ol>
* All those customizations are applied selectively on the Table cells thanks to a {@link CellMatcher}: One can

17
src/main/java/org/springframework/shell/table/TableBuilder.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2015 the original author or authors.
* Copyright 2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -60,6 +60,8 @@ public class TableBuilder {
* <li>{@link DelimiterTextWrapper wrapping text} on space characters</li>
* <li>{@link SimpleHorizontalAligner left aligning} text.</li>
* </ul>
*
* @param model the data model of the table to construct
*/
public TableBuilder(TableModel model) {
@@ -109,6 +111,8 @@ public class TableBuilder {
/**
* Set a border on the outline of the whole table.
* @param style the style to apply
* @return this, for method chaining
*/
public TableBuilder addOutlineBorder(BorderStyle style) {
this.addBorder(0, 0, model.getRowCount(), model.getColumnCount(), OUTLINE, style);
@@ -117,6 +121,8 @@ public class TableBuilder {
/**
* Set a border on the outline of the whole table, as well as around the first row.
* @param style the style to apply
* @return this, for method chaining
*/
public TableBuilder addHeaderBorder(BorderStyle style) {
this.addBorder(0, 0, 1, model.getColumnCount(), OUTLINE, style);
@@ -125,6 +131,9 @@ public class TableBuilder {
/**
* Set a border around each and every cell of the table.
*
* @param style the style to apply
* @return this, for method chaining
*/
public TableBuilder addFullBorder(BorderStyle style) {
this.addBorder(0, 0, model.getRowCount(), model.getColumnCount(), FULL, style);
@@ -134,6 +143,9 @@ public class TableBuilder {
/**
* Set a border on the outline of the whole table, around the first row and draw vertical lines
* around each column.
*
* @param style the style to apply
* @return this, for method chaining
*/
public TableBuilder addHeaderAndVerticalsBorders(BorderStyle style) {
this.addBorder(0, 0, 1, model.getColumnCount(), OUTLINE, style);
@@ -143,6 +155,9 @@ public class TableBuilder {
/**
* Set a border on the inner verticals and horizontals of the table, but not on the outline.
*
* @param style the style to apply
* @return this, for method chaining
*/
public TableBuilder addInnerBorder(BorderStyle style) {
this.addBorder(0, 0, model.getRowCount(), model.getColumnCount(), INNER, style);

12
src/main/java/org/springframework/shell/table/TableModel.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2015 the original author or authors.
* Copyright 2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -24,24 +24,26 @@ package org.springframework.shell.table;
public abstract class TableModel {
/**
* Return the number of rows that can be queried.
* @return the number of rows that can be queried.
* Values between 0 and {@code rowCount-1} inclusive are valid values.
*/
public abstract int getRowCount();
/**
* Return the number of columns that can be queried.
* @return the number of columns that can be queried.
* Values between 0 and {@code columnCount-1} inclusive are valid values.
*/
public abstract int getColumnCount();
/**
* Return the data value to be displayed at a given row and column, which may be null.
* @return the data value to be displayed at a given row and column, which may be null.
* @param row the row that is being queried
* @param column the column that is being queried
*/
public abstract Object getValue(int row, int column);
/**
* Return a transposed view of this model, where rows become columns and vice-versa.
* @return a transposed view of this model, where rows become columns and vice-versa.
*/
public TableModel transpose() {
return new TableModel() {

6
src/main/java/org/springframework/shell/table/Tables.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2015 the original author or authors.
* Copyright 2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -27,6 +27,10 @@ public class Tables {
/**
* Install all the necessary formatters, aligners, etc for key-value rendering of Maps.
*
* @param builder the builder to configure
* @param delimiter the delimiter to apply between keys and values
* @return buider for method chaining
*/
public static TableBuilder configureKeyValueRendering(TableBuilder builder, String delimiter) {
return builder.on(CellMatchers.ofType(Map.class))

9
src/main/java/org/springframework/shell/table/TextWrapper.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2015 the original author or authors.
* Copyright 2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -18,13 +18,18 @@ package org.springframework.shell.table;
/**
* A strategy for applying text wrapping/cropping given a cell width.
*
* @author Eric Bottard
*/
public interface TextWrapper {
/**
* Return a list of lines where each line length MUST be equal to {@code columnWidth} (padding with spaces if
* @return a list of lines where each line length MUST be equal to {@code columnWidth} (padding with spaces if
* appropriate). There is no constraint on the number of lines returned however (typically, will be greater than
* the input number if wrapping occurred).
*
* @param original the text in its original form
* @param columnWidth the width to conform to
*/
String[] wrap(String[] original, int columnWidth);
}