Overview | Package | Class | Use | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.togethersoft.openapi.rwi
Interface RwiPropertyMap

All Known Subinterfaces:
  RwiContainer, RwiDiagram, RwiDiagramReference, RwiElement, RwiLink, RwiLinkReference, RwiMember, RwiMemberReference, RwiNode, RwiNodeReference, RwiPackage, RwiReference

public interface RwiPropertyMap

Represents a container for the properties. `RwiElement` interface extends this interface inheriting all its methods for working with properties.

### Introduction

Properties contain the element's behavioral and structural data, like name, type, contents etc.

Each property has:

- A name. Names of the predefined properties ("hardcoded" properties) are in the RwiProperty interface.
- A value. It can be either `boolean` or `String`.

Some properties can be read- or write-only.

An element can have single or multiple instances of a string property with the same name. (That is there can be five (for example) string properties with the name "author" (and their values can be the same or different - it does not matter)). The number of instances of a property with the same name an element can have depends on the kind of information being represented by the property. For example, for obvious reasons there can be only one RwiProperty.NAME or RwiProperty.RETURN_TYPE property, but several RwiProperty.PARAMETER properties.

In the description of each property in the `RwiProperty` interface it is stated how many instances of that property an element can have.

String properties are represented by the RwiProperty instances. This interface defines several useful methods allowing to work with a string property in-depth (you can query it whether the property is read-only, or get additional information containing in the property (yes, hardcoded string properties can contain something else besides its value) - this is discussed in the `RwiProperty` documentation).

An element cannot have multiple instances of `boolean` property with the same name - it is obvious why - they represent some kind of a binary state.

### Working with the properties

This interface provides two sets of methods for working with the properties which depend on the type of the property:

- String properties.
  - Creating a property
    - setProperty(String propertyName, String propertyValue) method is used for creating a single instance of a string property.
    - addProperty(String propertyName, String propertyValue) method is used for creating multiple instances of a string property.
  - Getting a value or a property
    - hasProperty(String propertyName) method is used to check whether this element has a string property.
    - getProperty(String propertyName) method returns the value of a string property or `null` if an element doesn't have such a property. Important: when working with the string properties which can have multiple instances, method `properties(String propertyName)` (below) should be used.
    - properties(String propertyName) method returns an enumeration of all the instances of the string property with the specified name. Note that this method returns not an enumeration of strings with the values of the property but an enumeration of `RwiProperty`s. Use the RwiProperty.getValue method to get the value of each property:

             RwiPropertyEnumeration files=somePackage.properties(RwiProperty.FILES);
             while (files.hasMoreElements()){
               System.out.println("Package contains a file :"+files.nextRwiProperty().getValue());
             }

      (see RwiProperty.FILES property description to understand this example)

- Boolean properties.
  - Creating a property
    - setProperty(String propertyName, boolean propertyValue) method is used for creating and changing a boolean property.
  - Getting a value or a property
    - hasProperty(String propertyName) method returns the value of a boolean property.

A property can be hardcoded or user-defined:

- hardcoded properties (their names, to be more specific) are defined in the RwiProperty interface. Together automatically assigns them to the elements depending on the kind of the element and other conditions.

  For example, if some `RwiNode` represents a public class it will have RwiProperty.PUBLIC property; if some `RwiMember` represents an operation it will have the RwiProperty.RETURN_TYPE property etc.

- user-defined properties can be set for any element except `RwiPackage` by the user using methods `setProperty(String, String), addProperty, setProperty(String, boolean)`. The only restriction is that the names of user-defined properties cannot begin with "$".

  For example, suppose you have a string property named "lastModified" which keeps the date of last modification of the element. When your script modifies some element, it updates/sets this property (this way you can track the dates for modifications of single attributes, operations etc).

  You work with a user-defined property in exactly the same manner you work with the hardcoded properties, except that you just specify the name of your property, not a name from `RwiProperty` interface: ``

       public static final String LAST_MODIFIED_PROPERTY_NAME = "lastModified";
       ...
       String modificationDate = someRwiElement.getProperty(LAST_MODIFIED_PROPERTY_NAME);
       if (modificationDate != null) {
         // the element has this property, analyze the value.
       }
       ... //modify the element
       someRwiElement.setProperty(LAST_MODIFIED_PROPERTY_NAME, "today!"); //we omit the normal code dealing with the Date to keep this sample simple

  Another examples of using the user-defined properties:

       someElement.setProperty("mySingleStringProperty", "itsValue"); // single string user-defined property
       someElement.addProperty("myMultipleStringProperty", "value1"); // multiple string user-defined property
       someElement.addProperty("myMultipleStringProperty", "value2"); // multiple string user-defined property
       someElement.setProperty("myBooleanProperty", true); // boolean user-defined property

- `properties()` method returns an enumeration of all the user-defined properties this element has.
- It is possible to delete a user-defined property from the elmenent:
  - A string user-defined property can be deleted using `setProperty(String propertyName, String propertyValue)` method and passing the `null` as the value of the property.
  - A boolean user-defined property can be deleted using `setProperty(String propertyName, boolean propertyValue)` method and passing the `false` as the value of the property.

In the source code-based elements properties are kept either in a or in the source code itself. For example, if a java operation `someOperation` has the RwiProperty.PRIVATE property then it has the "private" modifier in its declaration:

    private void someOperation(){}

Author:
  TogetherSoft
See Also: RwiProperty, RwiElement

Method Summary
`RwiProperty` | `addProperty(String propertyName, String propertyValue)` Creates a new instance of a specified string property.
`boolean` | `canAddProperty(String propertyName, String propertyValue)` Checks whether it is possible to add a new instance of a specified string property with the specified value.
`boolean` | `canSetProperty(String propertyName, String propertyValue)` Checks if the value is valid for the specified string property, and can be assigned to it at this time.
`boolean` | `canSetProperty(String propertyName, boolean propertyValue)` Checks if the value is valid for the specified boolean property, and can be assigned to it at this time.
`String` | `getProperty(String propertyName)` Returns the value of the specified property.
`boolean` | `hasProperty(String propertyName)` For boolean properties returns the value of the specified property, for string properties checks if this element has the specified property.
`boolean` | `isPropertyReadable(String propertyName)` Checks whether the specified property could be read.
`boolean` | `isPropertyWritable(String propertyName)` Checks whether the specified property could be changed.
`RwiPropertyEnumeration` | `properties()` Returns `RwiPropertyEnumeration` of all the user-defined properties this element has.
`RwiPropertyEnumeration` | `properties(String propertyName)` Returns an `RwiPropertyEnumeration` of all instances of the specified string property.
`void` | `setProperty(String propertyName, String propertyValue)` Sets the value of specified string property.
`void` | `setProperty(String propertyName, boolean propertyValue)` Sets the value of specified boolean property.

Method Detail

### addProperty

    public RwiProperty addProperty(String propertyName, String propertyValue)

  Creates a new instance of a specified string property. If the property with the same name is present in this element already, it is never replaced, but another instance of if is made. Thus the element will have several instances of the specified string property.

  To create a boolean property the method `setProperty(String, boolean)` should be used.

  Parameters:
    propertyName - the string with the name of a string property
    propertyValue - String value of a string property which will be assigned to it. Cannot be `null`
  Returns: new just added property
  See Also:
    setProperty(java.lang.String,boolean)

### canAddProperty

    public boolean canAddProperty(String propertyName, String propertyValue)

  Checks whether it is possible to add a new instance of a specified string property with the specified value.
  Parameters:
    propertyName - the string with the name of a string property
    propertyValue - string value of property which will be assigned to it
  Returns: `true` if it is possible to add new a instance of a specified string property, `false` otherwise
  See Also:
    RwiProperty

### canSetProperty

    public boolean canSetProperty(String propertyName, String propertyValue)

  Checks if the value is valid for the specified string property, and can be assigned to it at this time.
  Parameters:
    propertyName - the string with name of a string property
    propertyValue - the string value which needs to be assigned to the property
  Returns: `true` if the specified value can be assigned to the property, `false` otherwise
  See Also:
    RwiProperty

### canSetProperty

    public boolean canSetProperty(String propertyName, boolean propertyValue)

  Checks if the value is valid for the specified boolean property, and can be assigned to it at this time.
  Parameters:
    propertyName - the string with the name of a boolean property
    propertyValue - the boolean value which needs to be assigned to the property
  Returns: `true` if the specified value can be assigned to the property, `false` otherwise
  See Also:
    RwiProperty

### getProperty

    public String getProperty(String propertyName)

  Returns the value of the specified property. If this element doesn't have such a property, method returns `null`.

  Important: for boolean properties method `hasProperty` should be used to obtain a value of a property.

  Parameters:
    propertyName - the string with the name of a property
  Returns: returns the value of the specified property
  See Also:
    hasProperty(java.lang.String), RwiProperty

### hasProperty

    public boolean hasProperty(String propertyName)

  For boolean properties returns the value of the specified property, for string properties checks if this element has the specified property.
  Parameters:
    propertyName - the string with a name of a property
  Returns: For boolean properties returns the value of the specified property, for string properties checks if this element has the specified property
  See Also:
    RwiProperty

### isPropertyReadable

    public boolean isPropertyReadable(String propertyName)

  Checks whether the specified property could be read. Some properties are write-only.
  Parameters:
    propertyName - the string with the name of a property
  Returns: `true` if the property can be read, `false` otherwise
  See Also:
    RwiProperty

### isPropertyWritable

    public boolean isPropertyWritable(String propertyName)

  Checks whether the specified property could be changed. Some properties are read-only, or the whole element might be read-only.
  Parameters:
    propertyName - the string with the name of a property
  Returns: `true` if the property can be changed, `false` otherwise
  See Also:
    RwiProperty

### properties

    public RwiPropertyEnumeration properties()

  Returns `RwiPropertyEnumeration` of all the user-defined properties this element has.
  Returns: `RwiPropertyEnumeration` of all the user-defined properties this element has
  See Also:
    RwiProperty

### properties

    public RwiPropertyEnumeration properties(String propertyName)

  Returns an `RwiPropertyEnumeration` of all instances of the specified string property. For example:

         RwiPropertyEnumeration extended = someRwiNode.properties(RwiProperty.EXTENDS);
         while (extended.hasMoreElements()){
           RwiProperty nextExtended=extended.nextRwiProperty();
           System.out.println("Our class/interface extends a class/interface :"+nextExtended.getValue());
           RwiPropertyMap subpropertiesContainer = nextExtended.getSubproperties();
           RwiModel model = RwiModelAccess.getModel();
           RwiElement foundClassOrInterface = model.findElement(subpropertiesContainer.getProperty(RwiProperty.REFERENCED_ELEMENT));
           if (foundClassOrInterface != null) {
              System.out.println("  The fully qualified name of this class/interface is :"+foundClassOrInterface.getProperty(RwiProperty.FULL_NAME));
           }
         }

  Parameters:
    propertyName - the string with the name of a string property
  Returns: RwiPropertyEnumeration returns an enumeration of all instances of the specified string property
  See Also:
    RwiProperty, RwiProperty.EXTENDS, RwiProperty.REFERENCED_ELEMENT

### setProperty

    public void setProperty(String propertyName, String propertyValue)

  Sets the value of specified string property. If this element has one or more propeties with the specified name already, method deletes them all and creates a new instance of a string property with the specified value.

  For creating multiple instances of the specified string property method `addProperty` should be used.

  For user-defined properties if `propertyValue` is `null`, then this property will be deleted.

  Parameters:
    propertyName - the string with the name of a string property
    propertyValue - the string with the value for the property
  See Also:
    addProperty(java.lang.String,java.lang.String), getProperty(java.lang.String), hasProperty(java.lang.String), RwiProperty

### setProperty

    public void setProperty(String propertyName, boolean propertyValue)

  Sets the value of specified boolean property. For user-defined properties if `propertyValue` is `false`, then this property will be deleted.

  Method `hasProperty` should be used for getting the value of a boolean property.

  Parameters:
    propertyName - the string with the name of a boolean property
    propertyValue - boolean value of the property
  See Also:
    hasProperty(java.lang.String), RwiProperty

Overview | Package | Class | Use | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD