SettingsNode (Gradle API 1.0)

All Known Implementing Classes:

DOM4JSettingsNode, SettingsNodeVersionWrapper
```
public interface SettingsNode
```
This provides a mechanism for storing settings. It is a hybrid of a DOM (like xml) and something much simpler like the java preferences. It is first meant to be easy to use. Second, it is supposed to abstract how the settings are actually stored. The point is to allow IDEs and such to store this is whatever manner they choose. Thus, this is vague. Third, it is meant to be relatively easy to implement. While this is a hiearchy, it is not meant to be as complex as XML with arbitrary attributes. Instead, it is only meant to be a key-value pairing. However, the hiearchy allows you to easily have lists and other complex structures without having to worry about name collisions as you would if this were a pure key-value pair. This is meant to be a single tree for the entire application. You shouldn't create these on your own. A node for your use should be given to you by your parent. Only the highest level object should directly create an instance of one of these. It should manage saving and restore these settings. Due to how some 'owners' of the settings work, you should save your settings immediately here (think of this as you would a database). Why? Well, for example: when Idea is the owner in the gradle Idea plugin, it attempts to store its settings very frequently and uses differences in the results to determine if changes have been made to a plugin. As a result, we store things in the setting immediately. This node consists to 3 things: - name: this is the 'key' of key-value pair. It is required. - value: this is the 'value' of key-value pair. It is NOT required. - child nodes: each node can have children nodes. Using these you can create a tree structure storing whatever you like. If you need multiple attributes like XML has, you should create children instead. So if, in xml, you wanted to do: do this instead: node name="myName" value="myvalue" node name="myotherattribute" value="attribute1" node name="somethingelse" value="attribute2" This has several convenience functions for setting and getting values from child nodes. These are meant to be used in more of a java preferences replacement. You should create your own root node of your settings (by call addChildIfNotPresent from a node that is given to you) then you can use these functions and you only need to worry about uniqueness within your own node.

Author:

mhunsicker

Method Summary

Methods
Modifier and Type	Method and Description
`SettingsNode`	`addChild(String name)` Call this to add a child node to this node.
`SettingsNode`	`addChildIfNotPresent(String name)` This adds a child node with the specified name or returns the existing child node if one already exists with said name.
`SettingsNode`	`getChildNode(String name)` Returns the child node with the specified name.
`List<SettingsNode>`	`getChildNodes()`
`List<SettingsNode>`	`getChildNodes(String name)`
`String`	`getName()`
`SettingsNode`	`getNodeAtPath(String... pathPortions)` Returns a node at the specified path starting at 'this' node.
`String`	`getValue()`
`String`	`getValueOfChild(String name, String defaultValue)` Gets the value of the child node.
`boolean`	`getValueOfChildAsBoolean(String name, boolean defaultValue)`
`int`	`getValueOfChildAsInt(String name, int defaultValue)` Gets the value of the child node as an integer.
`long`	`getValueOfChildAsLong(String name, long defaultValue)`
`void`	`removeAllChildren()` Deletes all the children of this node.
`void`	`removeFromParent()` Removes this node from its parent.
`void`	`setName(String name)` Sets the name of this node.
`void`	`setValue(String value)` Sets the value of this node.
`void`	`setValueOfChild(String name, String value)` Sets the value of the child node, adding it if it is not already present.
`void`	`setValueOfChildAsBoolean(String name, boolean value)`
`void`	`setValueOfChildAsInt(String name, int value)` Sets the value of the child node as an integer, adding it if it is not already present.
`void`	`setValueOfChildAsLong(String name, long value)`

- Method Detail
  - setName
```
void setName(String name)
```
    Sets the name of this node. This is used as its identifier.
    
    Parameters:
    name - the new name. Cannot be null!
  - getName
```
String getName()
```
  - setValue
```
void setValue(String value)
```
    Sets the value of this node. This is whatever you like, but is always internally text.
    
    Parameters:
    value - the new value. Can be null.
  - getValue
```
String getValue()
```
  - setValueOfChild
```
void setValueOfChild(String name,
                   String value)
```
    Sets the value of the child node, adding it if it is not already present. This is a convenience function providing more java preferences-like behavior.
    
    Parameters:
    name - the name of the child node.
    value - the new value.
  - getValueOfChild
```
String getValueOfChild(String name,
                     String defaultValue)
```
    Gets the value of the child node. If it is not present, the defaultValue is returned. This is a convenience function providing more java preferences-like behavior.
    
    Parameters:
    name - the name of the child node.
    defaultValue - the value to return if the child node is not present
    
    Returns:
    the value.
  - setValueOfChildAsInt
```
void setValueOfChildAsInt(String name,
                        int value)
```
    Sets the value of the child node as an integer, adding it if it is not already present. This is a convenience function providing more java preferences-like behavior.
    
    Parameters:
    name - the name of the child node.
    value - the new value.
  - getValueOfChildAsInt
```
int getValueOfChildAsInt(String name,
                       int defaultValue)
```
    Gets the value of the child node as an integer. If it is not present or the value is cannot be interpretted as an integer, the defaultValue is returned. This is a convenience function providing more java preferences-like behavior.
    
    Parameters:
    name - the name of the child node.
    defaultValue - the value to return if the child node is not present or cannot be interpretted as an integer.
    
    Returns:
    the value.
  - setValueOfChildAsBoolean
```
void setValueOfChildAsBoolean(String name,
                            boolean value)
```
  - getValueOfChildAsBoolean
```
boolean getValueOfChildAsBoolean(String name,
                               boolean defaultValue)
```
  - setValueOfChildAsLong
```
void setValueOfChildAsLong(String name,
                         long value)
```
  - getValueOfChildAsLong
```
long getValueOfChildAsLong(String name,
                         long defaultValue)
```
  - getChildNodes
```
List<SettingsNode> getChildNodes()
```
    Returns:
    a list of all child nodes of this node.
  - getChildNodes
```
List<SettingsNode> getChildNodes(String name)
```
    Parameters:
    name - the names of the sought child nodes.
    
    Returns:
    a list of all child nodes of this node that have the specified name. If none are found, this should return an empty list. Never null.
  - getChildNode
```
SettingsNode getChildNode(String name)
```
    Returns the child node with the specified name.
    
    Parameters:
    name - the name of the sought node
    
    Returns:
    the child settings node or null if no match found.
  - addChild
```
SettingsNode addChild(String name)
```
    Call this to add a child node to this node.
    
    Parameters:
    name - the name of the node
    
    Returns:
    the child settings node.
  - addChildIfNotPresent
```
SettingsNode addChildIfNotPresent(String name)
```
    This adds a child node with the specified name or returns the existing child node if one already exists with said name.
    
    Parameters:
    name - the name.
    
    Returns:
    the child settings node. Never null.
  - getNodeAtPath
```
SettingsNode getNodeAtPath(String... pathPortions)
```
    Returns a node at the specified path starting at 'this' node.
    
    Parameters:
    pathPortions - an array of 'names' of the nodes. The first item corresponds to a direct child of this node. The second item would be the grand child of this node. etc. etc.
    
    Returns:
    a node if it exists. Null if not.
  - removeFromParent
```
void removeFromParent()
```
    Removes this node from its parent.
  - removeAllChildren
```
void removeAllChildren()
```
    Deletes all the children of this node.

Interface SettingsNode

Method Summary

Method Detail

setName

getName

setValue

getValue

setValueOfChild

getValueOfChild

setValueOfChildAsInt

getValueOfChildAsInt

setValueOfChildAsBoolean

getValueOfChildAsBoolean

setValueOfChildAsLong

getValueOfChildAsLong

getChildNodes

getChildNodes

getChildNode

addChild

addChildIfNotPresent

getNodeAtPath

removeFromParent

removeAllChildren