Skip to content
Utilities and software patterns commonly associated with data objects
Fantom
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.f4
dev
doc
fan
svg
test
.buildpath
.classpath
.gitignore
.hgignore
.project
build.fan
js-help.txt
readme.md

readme.md

Bean Utils v1.0.10


Written in: Fantom pod: v1.0.10 Licence: ISC

Overview

Bean Utils is a support library that aids Alien-Factory in the development of other libraries, frameworks and applications. Though you are welcome to use it, you may find features are missing and the documentation incomplete.

Bean Utils is a collection of utilities and software patterns for overcoming common issues associated with data objects.

Features include:

  • Bean Builder

    Static methods for creating Fantom objects. Don't make() your beans, build() them instead!

  • Bean Equality

    Generate equals(), hash() and toStr() methods from fields.

  • Bean Properties

    Get and set object properties and call methods via property expressions.

  • Type Coercer

    Convert objects, lists and maps from one type to another using Fantom's standard toXXX() and fromXXX() methods.

  • More!

    Utility methods to find matching ctors and methods.

Bean Utils is loosely named after JavaBeans,

Install

Install Bean Utils with the Fantom Pod Manager ( FPM ):

C:\> fpm install afBeanUtils

Or install Bean Utils with fanr:

C:\> fanr install -r http://eggbox.fantomfactory.org/fanr/ afBeanUtils

To use in a Fantom project, add a dependency to build.fan:

depends = ["sys 1.0", ..., "afBeanUtils 1.0"]

Documentation

Full API & fandocs are available on the Eggbox - the Fantom Pod Repository.

Bean Equality

Nobody likes writing hash() and equals() methods, so let BeanEquality take the pain away! Simply annotate important identity fields with @BeanId and override the Obj methods.

Sample usage:

class User {
    Int? id
    Str? name
    Str? wotever

    override Int hash() {
      BeanEquality.beanHash(this, [#id, #name])
    }

    override Bool equals(Obj? obj) {
      BeanEquality.beanEquals(this, obj, [#id, #name])
    }

    override Str toStr() {
      BeanEquality.beanToStr(this, [#id, #name])
    }
}

Bean Properties

BeanProperties is a nifty way to get and set properties, and call methods, on nested objects.

Properties are accessed via a property expression. Property expressions look like Fantom code and may traverse many objects. Their main purpose is to get and set properties, but may be used to call methods also.

string := "100 101 102"
BeanProperties.call(string, "split[1].get(2).plus(2).toChar") // --> 3

Using BeanProperties and a bit of naming convention care, it now becomes trivial to populate an object with properties submitted from a HTTP form:

formBean := BeanProperties.create(MyFormBean#, httpReq.form)

Features of property expressions include:

Field Access

The simplest use case is getting and setting basic fields. In this example we access the field Buf.capacity:

buf := Buf()
BeanProperties.get(buf, "capacity")     // --> 16
BeanProperties.set(buf, "capacity", 42) // set a new value

When setting fields, the given value is Type Coerced to fit the field type. Consider:

BeanProperties.set(buf, "charset", "UTF-16")  // string "UTF-16" is converted to a Charset object

Method Calls

Property expressions can call methods too. Like Fantom code, if the method does not take any parameters then brackets are optional:

buf := Buf()
BeanProperties.call(buf, "flush")
BeanProperties.call(buf, "flush()")

Method arguments may also form part of the expression, and like property values, are type coerced to their respective types:

BeanProperties.call(buf, "fill(255, 4)")    // --> 0xFFFFFFFF
BeanProperties.call(buf, "getRange(1..2)")  // --> 0xFFFF

Or you may pass arguments in:

BeanProperties.call(buf, "fill", [128, 4])      // --> 0x80808080
BeanProperties.call(buf, "getRange()", [1..2])  // --> 0x8080

Indexed Properties

Lists, Maps and @Operator shortcuts for get and set may all be traversed using square bracket notation:

list := Str?["a", "b", "c"]
BeanProperties.get(list, "[1]") // --> "b"

All keys and values are Type Coerced to the correct type.

Lists

When setting List items special attention is given make sure they don't throw IndexErrs. Should the list size be smaller than the given index, the list is automatically grown to accommodate:

list := Str?[,]
BeanProperties.set(list, "[1]", "b")
list.size                            // --> 2
list[0]                              // --> null
list[1]                              // --> "b"

If the list items are not nullable, then new objects are created:

list := Str[,]
BeanProperties.set(list, "[1]", "b")
list.size                            // --> 2
list[0]                              // --> ""
list[1]                              // --> "b"

Chaining

Property expressions become very powerful when chained:

obj.method(arg, arg).map[key].list[idx][operator].field

Object Creation

When traversing a property expression, the last thing you want is a NullErr half way through. With that in mind, should a property expression encounter null part way through, a new object is created and set.

Now you can happily chain your expressions with confidence!

Advanced

If you need more control over when and how intermediate objects are created, then use BeanPropertyFactory to manually parse property expressions and create your own BeanProperty instances.

You can’t perform that action at this time.