dev.dejvokep.boostedyaml.route

Interface Route

All Known Implementing Classes:

MultiKeyRoute, SingleKeyRoute

public interface Route

Routes are URI-like objects used to access and modify data stored in sections, backed by a simple array.

Routes are immutable objects - it is recommended to create individual objects only once and reuse them. Route's keys are traversed in order as given: assuming route ["x", 1], the processing method (Section getter/setter...) attempts to obtain section at key "x" in the section from which the method was called; and then value at key 1 in that section.

Method Summary

Modifier and Type	Method and Description
Route	add(Object key) Adds the given non-null key to the route and returns the new object.
static Route	addTo(Route route, Object key) Adds the given non-null key to the route and returns the new object, if the route is null, creates and returns a single key route containing only the key.
boolean	equals(Object o)
static Route	from(Object... route) Constructs a route from the given non-null keys.
static Route	from(Object key) Constructs a route from the given non-null key.
static Route	fromSingleKey(Object key) Constructs a route from the given non-null key.
static Route	fromString(String route) Constructs a route by splitting the given string route by GeneralSettings.DEFAULT_ROUTE_SEPARATOR.
static Route	fromString(String route, char separator) Constructs a route by splitting the given string route by the provided separator.
static Route	fromString(String route, RouteFactory routeFactory) Constructs a route by splitting the given string route by the provided factory's separator.
Object	get(int i) Returns key at the given index.
int	hashCode()
String	join(char separator) Joins the route's keys with the given separator.
int	length() Returns the length of the route (backing array) - amount of keys forming the route.
Route	parent() Returns the parent route of this one.

Method Detail

from

@NotNull
static Route from(@NotNull
                            Object... route)

Constructs a route from the given non-null keys. The given keys must be immutable; if this cannot be achieved, it is required that the caller never modifies them.

No keys or an empty array is considered illegal and will throw an IllegalArgumentException. As indicated, null keys or attempt to pass a null array (to avoid varargs functionality, e.g. from((Object[]) null)) will throw a NullPointerException.

If passing an array as the only key, do not forget to cast it to Object, or use fromSingleKey(Object) instead.

Parameters:

route - the route keys

Returns:

the route

See Also:

implementation information

from

@NotNull
static Route from(@NotNull
                            Object key)

Constructs a route from the given non-null key. The given key must be immutable; if this cannot be achieved, it is required that the caller never modifies it.

As indicated, the given key cannot be null. Such attempt will result in a NullPointerException.

Parameters:

key - the single key in the route

Returns:

the single key route

See Also:

alias, implementation information

fromSingleKey

@NotNull
static Route fromSingleKey(@NotNull
                                     Object key)

Constructs a route from the given non-null key. The given key must be immutable; if this cannot be achieved, it is required that the caller never modifies it.

As indicated, the given key cannot be null. Such attempt will result in a NullPointerException.

Parameters:

key - the single key in the route

Returns:

the single key route

See Also:

implementation information

fromString

@NotNull
static Route fromString(@NotNull
                                  String route)

Constructs a route by splitting the given string route by GeneralSettings.DEFAULT_ROUTE_SEPARATOR. To split using a custom separator, use fromString(String, char) instead.

For example, giving string route "a.b" will return the equivalent route containing 2 keys: ["a", "b"].

Please note that string routes can also be used as Route objects, therefore you should not introduce additional overhead by converting them using methods provided by this class, unless necessarily needed.

Parameters:

route - the string route to split

Returns:

the route

See Also:

fromString(String, char), implementation information

fromString

@NotNull
static Route fromString(@NotNull
                                  String route,
                                  char separator)

Constructs a route by splitting the given string route by the provided separator.

For example, giving string route "a/b" and separator / will return the equivalent route containing 2 keys - ["a", "b"].

Please note that string routes can also be used as Route objects, therefore you should not introduce additional overhead by converting them using methods provided by this class, unless necessarily needed. If that's the case for multiple routes, you can use RouteFactory to abstract the separator.

Parameters:

route - the string route to split

separator - separator to split the route by

Returns:

the route

See Also:

fromString(String, char), implementation information

fromString

@NotNull
static Route fromString(@NotNull
                                  String route,
                                  @NotNull
                                  RouteFactory routeFactory)

Constructs a route by splitting the given string route by the provided factory's separator.

For example, giving string route "a/b" and separator / will return the equivalent route containing 2 keys - ["a", "b"].

Please note that string routes can also be used as Route objects, therefore you should not introduce additional overhead by converting them using methods provided by this class, unless necessarily needed.

Parameters:

route - the string route to split

routeFactory - provider of the separator

Returns:

the route

See Also:

fromString(String, char), implementation information

addTo

@NotNull
static Route addTo(@Nullable
                             Route route,
                             @NotNull
                             Object key)

Adds the given non-null key to the route and returns the new object, if the route is null, creates and returns a single key route containing only the key. The given key must be immutable; if this cannot be achieved, it is required that the caller never modifies it.

For example, if you add key 1 to route ["a", "b"], the resulting route will be represented by ["a", "b", 1]. However, if you add the same key to a null route, the result will be a single key route equivalent to [1].

More formally, if a non-null route is given, copies this route's backing array (keys), adds the given key at the end and returns the new route.

Parameters:

route - route to add the key to, or null to create a single key route

key - the key to add

Returns:

the new route with same keys as this one, except with the given key added as the last one

See Also:

addTo(Route, Object)

join

@NotNull
String join(char separator)

Joins the route's keys with the given separator.

Parameters:

separator - the separator to join with

Returns:

the joined route

length

int length()

Returns the length of the route (backing array) - amount of keys forming the route.

Returns:

the length

get

@NotNull
Object get(int i)

Returns key at the given index. Always verify if the requested index is within the range of the backing array's length.

Parameters:

i - the index

Returns:

the key at the given index

add

@NotNull
Route add(@NotNull
                    Object key)

Adds the given non-null key to the route and returns the new object. The given key must be immutable; if this cannot be achieved, it is required that the caller never modifies it.

For example, if you add key 1 to route ["a", "b"], the resulting route will be represented by ["a", "b", 1].

More formally, copies this route's backing array (keys), adds the given key at the end and returns the new route.

Parameters:

key - the key to add

Returns:

the new route with same keys as this one, except with the given key added as the last one

parent

@NotNull
Route parent()

Returns the parent route of this one. More formally, creates a new route and copies this route's backing array without the last element.

Per documentation of from(Object...), invoking this method if length() == 1 will throw an IllegalArgumentException.

Returns:

the parent route

equals

boolean equals(Object o)

Overrides:

equals in class Object

hashCode

int hashCode()

Overrides:

hashCode in class Object