DialogPlace (JavaDocs for mmm-all dev-SNAPSHOT)

java.lang.Object
- net.sf.mmm.client.ui.api.dialog.DialogPlace

```
public class DialogPlace
extends Object
```
This is the interface for an object that identifies a dialog in combination with its getParameters(). It allows to represent a specific state of the client that can be bookmarked and reopened at a later point in time.
HINT:
For each of your Dialog you need to define a dialog-id. To decouple your navigation from the actual dialogs and their implementation, it is recommended to define them in a central interface (you can also have multiple such interfaces or classes for large modular systems). See DialogConstants to get started. For Dialogs may have mandatory or optional parameters it is further recommended to create sub-classes for DialogPlace or to define a factory for your DialogPlaces that takes the parameter values as properly typed arguments. This will make refactoring easier if parameters need to be changed. If you are sub-classing DialogPlace please be aware that your DialogControllers are NOT permitted to cast DialogPlace to your sub-class as the navigation can also take place via URL typing or from a bookmark and the framework will NOT know your subclasses. For generic access to your parameters please also define PARAMETER_* constants in your DialogConstants.
```
 public class MyScreenDialogPlace extends DialogPlace {

   public MyScreenDialogPlace(Type mandatoryParameterFoo) {
     this(mandatoryParameterFoo, null);
   }

   public MyScreenDialogPlace(Type mandatoryParameterFoo, OtherType optionalParameterBar) {
     super(MyDialogConstants.DIALOG_ID_MY_SCREEN, addParameter(
      newParameter(MyDialogConstants.PARAMETER_MY_SCREEN_FOO, mandatoryParameterFoo),
      MyDialogConstants.PARAMETER_MY_SCREEN_BAR, optionalParameterBar, false));
   }
 }
 
```
If you do not need to open places in a new window, you can also combine your places with the DialogManager and instead of providing create methods you define methods like:
```
   public void navigateDocument(long documentId) {
     DialogPlace place = new DialogPlace(PLACE_DOCUMENT, createParameters(PARAM_DOCUMENT_ID, Long.toString(documentId));
     getDialogManager().navigateTo(place);
   }
 
```
Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields
Modifier and Type	Field and Description
`private String`	`dialogId`
`private Map<String,String>`	`parameters`
`static String`	`PATTERN_DIALOG_ID`
`static String`	`PATTERN_KEY` The regex pattern used to assert `parameter keys`.
`static String`	`PATTERN_VALUE` The regex pattern used to assert `parameter values`.
`static char`	`SEPARATOR_PARAMETER` The separator used between `parameters`.
`static char`	`SEPARATOR_STATE` The separator for `dialog-id` and its `parameters`.
`static char`	`SEPARATOR_VALUE` The separator for key and value of a `parameter`.
`private static SimpleGenericValueConverter`	`valueConverter`

Constructor Summary

Constructors
Modifier	Constructor and Description
	`DialogPlace(String dialogId)` The constructor.
`protected`	`DialogPlace(String dialogId, Map<String,String> parameters)` The constructor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected static Map<String,String>`	`addParameter(Map<String,String> parameters, String key, Object value)` Adds the given parameter to the given `Map`.
`protected static Map<String,String>`	`addParameter(Map<String,String> parameters, String key, Object value, boolean required)` Adds the given parameter to the given `Map`.
`boolean`	`equals(Object obj)`
`static DialogPlace`	`fromString(String place)` This is the inverse operation of `toString()`.
`String`	`getDialogId()` This method gets the `ID` of the `Dialog` identified by this `DialogPlace`.
`String`	`getParameter(String key)` This method gets a parameter of this `DialogPlace`.
`<T> T`	`getParameter(String key, Class<T> type)` This method gets a typed parameter of this `DialogPlace`.
`protected Map<String,String>`	`getParameters()`
`protected SimpleGenericValueConverter`	`getValueConverter()`
`int`	`hashCode()`
`boolean`	`hasParameter(String key)` This method determines if a `getParameter(String)` is present (!= null).
`protected static Map<String,String>`	`newParameter(String key, Object value)` Creates a `Map` with the given parameter.
`protected static Map<String,String>`	`newParameter(String key, Object value, boolean required)` Creates a `Map` with the given parameter.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - SEPARATOR_STATE
```
public static final char SEPARATOR_STATE
```
    The separator for dialog-id and its parameters.
    
    See Also:
    
    Constant Field Values
  - SEPARATOR_PARAMETER
```
public static final char SEPARATOR_PARAMETER
```
    The separator used between parameters.
    
    See Also:
    
    Constant Field Values
  - SEPARATOR_VALUE
```
public static final char SEPARATOR_VALUE
```
    The separator for key and value of a parameter.
    
    See Also:
    
    Constant Field Values
  - PATTERN_KEY
```
public static final String PATTERN_KEY
```
    The regex pattern used to assert parameter keys.
    
    See Also:
    
    Constant Field Values
  - PATTERN_VALUE
```
public static final String PATTERN_VALUE
```
    The regex pattern used to assert parameter values.
    
    See Also:
    
    Constant Field Values
  - PATTERN_DIALOG_ID
```
public static final String PATTERN_DIALOG_ID
```
    See Also:
    
    AbstractDialog.PATTERN_DIALOG_ID, Constant Field Values
  - dialogId
```
private final String dialogId
```
    See Also:
    
    getDialogId()
  - parameters
```
private Map<String,String> parameters
```
    See Also:
    
    getParameters()
  - valueConverter
```
private static SimpleGenericValueConverter valueConverter
```
    See Also:
    
    getValueConverter()
- Constructor Detail
  - DialogPlace
```
public DialogPlace(String dialogId)
```
    The constructor.
    
    Parameters:
    
    dialogId - - see getDialogId().
  - DialogPlace
```
protected DialogPlace(String dialogId,
                      Map<String,String> parameters)
```
    The constructor.
    
    Parameters:
    
    dialogId - - see getDialogId().
    
    parameters - - see getParameters().
- Method Detail
  - newParameter
```
protected static Map<String,String> newParameter(String key,
                                                 Object value)
```
    Creates a Map with the given parameter.
    
    Parameters:
    
    key - is the name of the parameter.
    
    value - is the value of the parameter.
    
    Returns:
    
    a new Map with the given parameter.
  - newParameter
```
protected static Map<String,String> newParameter(String key,
                                                 Object value,
                                                 boolean required)
```
    Creates a Map with the given parameter.
    
    Parameters:
    
    key - is the name of the parameter.
    
    value - is the value of the parameter. May be null if required is false. Then an empty Map is returned. Use the empty String instead of null to prevent this.
    
    required - - if false the given value may be null, true if the parameter is required and an exception shall be thrown if value is null.
    
    Returns:
    
    a new Map with the given parameter.
  - addParameter
```
protected static Map<String,String> addParameter(Map<String,String> parameters,
                                                 String key,
                                                 Object value)
```
    Adds the given parameter to the given Map.
    
    Parameters:
    
    parameters - is the map with the current parameters.
    
    key - is the name of the parameter.
    
    value - is the value of the parameter.
    
    Returns:
    
    the given parameters Map.
  - addParameter
```
protected static Map<String,String> addParameter(Map<String,String> parameters,
                                                 String key,
                                                 Object value,
                                                 boolean required)
```
    Adds the given parameter to the given Map.
    
    Parameters:
    
    parameters - is the map with the current parameters.
    
    key - is the name of the parameter.
    
    value - is the value of the parameter. May be null for generic usage with optional parameter. Then the given Map is returned unchanged. Use the empty String instead of null to prevent this.
    
    required - - if false the given value may be null, true if the parameter is required and an exception shall be thrown if value is null.
    
    Returns:
    
    the given parameters Map.
  - getDialogId
```
public final String getDialogId()
```
    This method gets the ID of the Dialog identified by this DialogPlace.
    
    Returns:
    
    the dialog ID.
  - getParameters
```
protected Map<String,String> getParameters()
```
    Returns:
    
    the parameterMap
  - hasParameter
```
public boolean hasParameter(String key)
```
    This method determines if a getParameter(String) is present (!= null).
    
    Parameters:
    
    key - is the name of the parameter to test.
    
    Returns:
    
    true if that parameter is present (NOT null), false otherwise.
  - getParameter
```
public String getParameter(String key)
```
    This method gets a parameter of this DialogPlace.
    
    Parameters:
    
    key - is the name of the requested parameter.
    
    Returns:
    
    the value of the requested parameter. Will be null if NOT set.
  - getParameter
```
public <T> T getParameter(String key,
                          Class<T> type)
```
    This method gets a typed parameter of this DialogPlace.
    
    Type Parameters:
    
    T - is the generic type of the desired parameter value.
    
    Parameters:
    
    key - is the name of the requested parameter.
    
    type - is the desired type of the parameter
    
    Returns:
    
    the value of the requested parameter converted to the given type. Will be null if NOT set.
  - getValueConverter
```
protected SimpleGenericValueConverter getValueConverter()
```
    Returns:
    
    the SimpleGenericValueConverter used for conversion in getParameter(String, Class).
  - fromString
```
public static DialogPlace fromString(String place)
```
    This is the inverse operation of toString().
    
    Parameters:
    
    place - is the string-representation of the DialogPlace to create.
    
    Returns:
    
    the according DialogPlace.
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class DialogPlace

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SEPARATOR_STATE

SEPARATOR_PARAMETER

SEPARATOR_VALUE

PATTERN_KEY

PATTERN_VALUE

PATTERN_DIALOG_ID

dialogId

parameters

valueConverter

Constructor Detail

DialogPlace

DialogPlace

Method Detail

newParameter

newParameter

addParameter

addParameter

getDialogId

getParameters

hasParameter

getParameter

getParameter

getValueConverter

fromString

hashCode

equals

toString