Skip to content

Latest commit

 

History

History
260 lines (212 loc) · 18.7 KB

README.md

File metadata and controls

260 lines (212 loc) · 18.7 KB
Raw

objects4j

A library with common Java types that are mostly immutable value objects.

Java Maven Build Coverage Status Maven Central LGPLv3 License Java Development Kit 17

Versions

  • 0.9.x (or later) = Java 17
  • 0.8.0 = Java 11 with new jakarta namespace
  • 0.7.x = Java 11 before namespace change from 'javax' to 'jakarta'
  • 0.6.9 (or previous) = Java 8

Features

Package "common"

Base classes like utilities and general annotations.

Package "ui"

Annotations that can be placed on plain objects but may be used by a user interface to render that object in some way.

Package "vo"

Provides Value Objects and utility classes for those immutable objects.

Click here for details...

Description "common"

Base classes like utilities and general annotations.

FileExists Validator

Verifies that the file exists (Bean validation JSR 303).

@FileExists
private File myFile;

IsDirectory Validator

Verifies that it's a directory and not a file (Bean validation JSR 303).

@IsDirectory
private File myDir;

TraceStringCapable

Marker interface for classes that provide a special representation for trace output.

public class MyClass implements TraceStringCapable {

   @Override
   public String toTraceString() {
       return "A long and very detailed instance description for trace output"; 
   }
   
}

Description "ui"

The annotations may be used by UI elements to display an appropriate text for a type or a field. You can also configure a bundle and key for internationalization.

Label annotation

Use this annotation to assign a label to a class or an attribute.

@Label(value = "Birthday", bundle = "my/MyBundle", key = "birthday.label")
private Date birthday;

Prompt annotation

Use this annotation to assign a prompt (example value) to a class or an attribute.

@Prompt(value = "12-31-1993", bundle = "my/MyBundle", key = "birthday.prompt")
private Date birthday;

ShortLabel annotation

Use this annotation to assign an abbreviation to a class or an attribute.

@ShortLabel(value = "BD", bundle = "my/MyBundle", key = "birthday.short")
private Date birthday;

TableColumn annotation

Use this annotation to assign preferred table column values to a field.

@TableColumn(pos = 3, width = 20, unit= FontSizeUnit.EM, getter = "isInternal")
private boolean permanentEmployee;

TextField annotation

Use this annotation to express the annotated attribute should be rendered as a text field. User agents are expected to use this information as hint for the rendering process.

@TextField(width = 50)
private String lastName;

Tooltip annotation

Use this annotation to assign a tooltip to a class or a field.

@Tooltip(value = "The person's birthday", bundle = "my/MyBundle", key = "birthday.tooltip")
private Date birthday;

AnnotationAnalyzer

You can use AnnotationAnalyzer to read the internationalized text from above annotations.

Read a single @Label text:

AnnotationAnalyzer analyzer = new AnnotationAnalyzer();

Field field = MyClass.class.getDeclaredField("birthday");

FieldTextInfo labelInfoGermany = analyzer.createFieldInfo(field, Locale.GERMANY, Label.class);        
System.out.println(labelInfoGermany.getText());
// Prints "Geburtstag"

FieldTextInfo labelInfoUs = analyzer.createFieldInfo(field, Locale.US, Label.class);        
System.out.println(labelInfoUs.getText());
// Prints "Birthday"

Read all @Label texts from a class:

AnnotationAnalyzer analyzer = new AnnotationAnalyzer();
List<FieldTextInfo> infos = analyzer.createFieldInfos(MyClass.class, Locale.US, Label.class);
for (final FieldTextInfo info : infos) {
	// Text of the label or the name of the field if the text is null
	System.out.println(info.getTextOrField());
}

Create a list of TableColumnInfo that combines @Label, @ShortLabel and @TableColumn annotations.

List<TableColumnInfo> columns = TableColumnInfo.create(MyClass.class, Locale.US);
for (TableColumnInfo column : columns) {
    System.out.println(column.getText());
}

This allows easy creation of a table model for example for JavaFX:

TableView<MyClass> tableView = new TableView<>();
List<TableColumnInfo> tableCols = TableColumnInfo.create(MyClass.class, Locale.getDefault());
Collections.sort(tableCols);
for (TableColumnInfo column : tableCols) {
    TableColumn<MyClass, String> tc = new TableColumn<>();
    tc.setStyle("-fx-alignment: CENTER;");
    Label label = new Label(column.getShortText());
    label.setTooltip(new Tooltip(column.getTooltip()));
    tc.setGraphic(label);
    tc.setCellValueFactory(new PropertyValueFactory<MyClass, String>(column.getField().getName()));
    tc.setPrefWidth(column.getWidth().getSize());
    tableView.getColumns().add(tc);
}

Examples annotation

Use this annotation to assign some example values to a class or an attribute.

@Examples({"John", "Jane"})
private String firstName;

Mappings annotation

Use this annotation to assign key/value mappings to a class or an attribute.

@Mappings({"1=One", "2=Two", "3=Three"})
private String code;

Description "vo"

Provides Value Objects (immutable objects) that represents an object whose equality isn't based on identity. That means instances of this type are equal when they have the same value, not necessarily being the same object. Additionally some helper classes (like validators) are placed in this package.

Interfaces

  • ValueObject - Tag interface for value objects.
  • ValueObjectConverter - Converts a value object into it's base type and back.
  • ValueObjectWithBaseType - Value object that may be expressed in a more general type with relaxed restrictions. Often basic Java types like String or numeric values (Long, Integer, ...) are used for this.
  • ValueOfCapable - Classes that can convert a string into a type (They have a valueOf(String) method).
  • AsStringCapable - Classes that provides a string representation (They have a asString() method).

Base classes that allow an easy implementation of concrete classes.

Predefined Value Objects

Validators

Other

  • KeyValue - Container for a key (String) and a value (Object).

Changes

0.7.0-SNAPSHOT

This version has several incompatible changes because of moving it to Java 11.

  • Removed JaxbMarshallable classes because of illegal reflective access

Snapshots

Snapshots can be found on the OSS Sonatype Snapshots Repository.

Add the following to your .m2/settings.xml to enable snapshots in your Maven build:

<repository>
    <id>sonatype.oss.snapshots</id>
    <name>Sonatype OSS Snapshot Repository</name>
    <url>http://oss.sonatype.org/content/repositories/snapshots</url>
    <releases>
        <enabled>false</enabled>
    </releases>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>