# PropertyConverter

Import: `import com.install4j.api.beaninfo.PropertyConverter;`

```java
interface PropertyConverter
```

A property converter translates between a string representation and the actual object state and provides
an optional [`property customizer`](PropertyCustomizer.md).
Property converters are registered on a per-bean basis with
[`Install4JBeanInfo.setPropertyConverters`](Install4JBeanInfo.md#setpropertyconverters-propertyconverter).

This interface and the [`PropertyCustomizer`](PropertyCustomizer.md) interface are similar to the `java.beans.PropertyEditor` class
which was not used in the install4j API since the editing concepts of the install4j IDE do not quite match with the
ideas in the java.beans API.

In concept, this class is similar to the [`EnumerationMapper`](EnumerationMapper.md) class.

## Methods

| Signature | Returns | Description |
|---|---|---|
| [`getPropertyClass()`](#getpropertyclass) | `Class` | Returns the property type for which this property converter is eligible. |
| [`getContext()`](#getcontext) | `String` | The property descriptor of a property that wants to use this property converter must have a non-null context that corresponds to the return value of this method. |
| [`toString(Object)`](#tostring-object) | `String` | Converts the property value to a string value. |
| [`supportsFromString()`](#supportsfromstring) | `boolean` | Returns if the property converter is able to convert a string representation to an object. |
| [`fromString(String)`](#fromstring-string) | `Object` | Converts a string representation to an object of type [`PropertyConverter.getPropertyClass`](PropertyConverter.md#getpropertyclass). |
| [`getPropertyCustomizerClass()`](#getpropertycustomizerclass) | `Class` | Returns the class of the optional property customizer. |

### getPropertyClass()

```java
Class getPropertyClass()
```

Returns the property type for which this property converter is eligible. Derived classes are also captured.


**Returns:** the property type

### getContext()

```java
String getContext()
```

The property descriptor of a property that wants to use this property converter must have a non-null context
that corresponds to the return value of this method. In this way, the runtime knows that this property converter
should be used for displaying and editing a property. The context must not be globally unique,
property converters of other property types can use the same context value.

For classes that do not have default handlers in install4j,
the property converter will also be used if this method returns [`PropertyConverter.DEFAULT_CONTEXT`](PropertyConverter.md#default-context), the 
[`PropertyConverter.getPropertyClass`](PropertyConverter.md#getpropertyclass) method returns the class of the property and the context of the property is not set.
However, it is safer not to rely on that behavior.


**Returns:** the context that will be used by the properties

### toString(Object)

```java
String toString(Object object)
```

Converts the property value to a string value. The string value will be displayed in the install4j IDE.
If [`PropertyConverter.supportsFromString`](PropertyConverter.md#supportsfromstring) returns `true`, the string value must be valid input for
[`PropertyConverter.fromString`](PropertyConverter.md#fromstring-string) and return an object with the same internal state.


**Parameters:**

- `object` — the property value of the type returned by [`PropertyConverter.getPropertyClass`](PropertyConverter.md#getpropertyclass) or possibly of a derived class

**Returns:** the string value

### supportsFromString()

```java
boolean supportsFromString()
```

Returns if the property converter is able to convert a string representation to an object.
If yes, the user will be able to edit the string returned by [`PropertyConverter.toString`](PropertyConverter.md#tostring-object) in the install4j IDE.


**Returns:** `true` if a string can be converted to an object

### fromString(String)

```java
Object fromString(String string)
```

Converts a string representation to an object of type [`PropertyConverter.getPropertyClass`](PropertyConverter.md#getpropertyclass).
When editing of the property is completed in the install4j IDE, this method will be called to construct an object that will be set as the
property value. This method is only called if [`PropertyConverter.supportsFromString`](PropertyConverter.md#supportsfromstring) returns `true`.


**Parameters:**

- `string` — the string representation

**Returns:** the object

### getPropertyCustomizerClass()

```java
Class getPropertyCustomizerClass()
```

Returns the class of the optional property customizer. If you want to offer a dialog where the user can edit the
property value, you have to implement [`PropertyCustomizer`](PropertyCustomizer.md) and return the name of your property customizer class,
otherwise return `null`.

If a non-null value is returned, the user will see a "..." button in the install4j IDE that brings up the dialog
with the property customizer.


**Returns:** the property customizer class or `null`

## Fields

| Field | Type | Description |
|---|---|---|
| [DEFAULT_CONTEXT](#default-context) | `String` | A default context that you can use in the [`PropertyConverter.getContext`](PropertyConverter.md#getcontext) method if there is only one property converter for the property type returned by [`PropertyConverter.getPropertyClass`](PropertyConverter.md#getpropertyclass) |

### DEFAULT_CONTEXT

```java
static final String DEFAULT_CONTEXT = "defaultConverterContext"
```

A default context that you can use in the [`PropertyConverter.getContext`](PropertyConverter.md#getcontext)  method if there is only one
property converter for the property type returned by [`PropertyConverter.getPropertyClass`](PropertyConverter.md#getpropertyclass)

