# Utils

The `Utils.groovy` file provides utility methods for our shared Jenkins libraries.

## Usage

### validateParams

The `validateParams` method validates each parameter against the provided rules and sets default values for optional parameters.
The validation rules are a map with the param names as key and a map of rules as value.

**Parameter rule options**:

- `type` (Class): The expected parameter type.
- `required` (Boolean): Indicates whether the parameter is required or not.
- `defaultValue` (any): Value to return for the parameter if it is not required and not provided.
- `itemType` (Class): The expected `List` item type. Requires the `type` parameter to be `List`.

```groovy
import com.sonymusic.Utils

def call(Map args) {
    def params = Utils.validateParams('myVar', args, [
        param1: [required: true, type: String],
        param2: [required: false, type: String, defaultValue: "default"]
    ])
}
```

In the example above, "param1" is validated as a String and that it has a value.
If it is not a String or not provided, the function will throw.

"param2" is validated as a String and will default to "default" if not provided.
It only throws if the type is incorrect. If the caller provided an unknown param e.g. "param3", the function will throw.

#### Validating List item types

```groovy
import com.sonymusic.Utils

def call(Map args) {
    def params = Utils.validateParams('myVar', args,  [
        stringsOnly: [required: true, type: List, itemType: String],
        numbersOnly: [required: false, type: List, itemType: Integer, defaultValue: []]
    ])
}
```
In the example above "stringsOnly" is validated as a List of strings and that it has a value. If it is not all strings or not provided, the function will throw.

The "numbersOnly" parameter is validated as a List and will default to [] if not provided. It only throws if the type or item types are incorrect.

### isTypeValid

The isTypeValid method checks if the value's type matches the expected type.

```groovy
import com.sonymusic.Utils

assert Utils.isTypeValid("value", String) == true
assert Utils.isTypeValid("value", List) == false
assert Utils.isTypeValid([], List) == true
assert Utils.isTypeValid([:], Map) == true
assert Utils.isTypeValid([], Map) == false

assert Utils.isTypeValid([1, 2, 3], List, Integer) == true
assert Utils.isTypeValid(["1", 2, "3"], List, Integer) == false

```

## Method Details

### validateParams

- **Parameters**:
  - `globalVarName`: The name of the global var to validate parameters for.
  - `params` (Map): A map containing parameters to validate.
  - `validationRules` (Map): A map defining validation rules for each parameter.
- **Returns**:
  - A map containing validated parameters and default values.
- **Throws**:
  - `IllegalArgumentException` if a parameter fails validation (e.g., missing required parameter, invalid type, unknown param).

### isTypeValid

- **Parameters**:
  - `value` (Object): The value to check.
  - `type` (Class): The expected type.
  - `itemType` (Class): Optional expected list item type.
- **Returns**:
  - `true` if the value's type matches the expected type, `false` otherwise.