org.openorb.property
Class PropertySetDefImpl

java.lang.Object
  extended by org.omg.PortableServer.Servant
      extended by org.omg.CosPropertyService.PropertySetDefPOA
          extended by org.openorb.property.PropertySetDefImpl
All Implemented Interfaces:
org.omg.CORBA.portable.InvokeHandler, PropertySetDefOperations, PropertySetOperations

public class PropertySetDefImpl
extends PropertySetDefPOA

PropertySetDefImpl is an implementation of the org.omg.CosPropertyService.PropertySetDef interface.

The PropertySetDef interface is a specialization (subclass) of the PropertySet interface. The PropertySetDef interface provides operations to retrieve PropertySet constraints, define and modify properties with modes, and to get or set property modes.

It should be noted that a PropertySetDef is still considered a PropertySet. The specialization operations are simply to provide more client access and control of the characteristics (metadata) of a PropertySet.

The PropertySetDef interface also provides "batch" operations, such as define_properties_with_modes, to deal with sets of property definitions as a whole. The execution of the "batch" operations is considered best effort (i.e., not an atomic set) in that not all suboperations need to succeed for any suboperation to succeed.

For define_properties_with_modes and set_property_modes, if any suboperation fails, a MultipleExceptions exception is returned to identify which property name had which exception.

For example, a client may invoke define_properties_with_modes using four property definition structures. The first property could be accepted (added or modified), the second could fail due to an UnsupportedMode, the third could fail due to a ConflictingProperty, and the fourth could fail due to ReadOnlyProperty.

In this case a property is either added or modified in the PropertySetDef and a MultipleExceptions exception is raised with three items in the PropertyExceptions sequence.

The get_property_modes "batch" operation utilizes a boolean flag to signal that mixed results occurred and additional processing may be required to fully analyze the exceptions.

Making "batch" operations behave in an atomic manner is considered an implementation issue that could be accomplished via specialization of this property service.

Author:
Jerome Daniel, Terence Song

Constructor Summary
PropertySetDefImpl(org.omg.CORBA.ORB orb)
          Creates a new (empty) instance of PropertySetDefImpl.
PropertySetDefImpl(org.omg.CORBA.ORB orb, PropertyDef[] initial_properties)
          Creates a new instance of PropertySetDefImpl with the specified initial properties.
PropertySetDefImpl(org.omg.CORBA.ORB orb, org.omg.CORBA.TypeCode[] allowed_property_types, PropertyDef[] allowed_properties)
          Creates a new instance of PropertySetDefImpl with the specified constraints.
 
Method Summary
 void define_properties_with_modes(PropertyDef[] property_defs)
          This operation will modify or add each of the properties in the Properties parameter to the PropertySet.
 void define_properties(Property[] nproperties)
          Modifies or adds each of the properties in Properties parameter to the PropertySet.
 void define_property_with_mode(java.lang.String property_name, org.omg.CORBA.Any property_value, PropertyModeType property_mode)
          This operation will modify or add a property to the PropertySet.
 void define_property(java.lang.String property_name, org.omg.CORBA.Any property_value)
          Modifies or adds a property to the PropertySet.
 boolean delete_all_properties()
          Variation of delete_properties.
 void delete_properties(java.lang.String[] property_names)
          Deletes the properties defined in the property_names parameter.
 void delete_property(java.lang.String property_name)
          Deletes the specified property if it exists from a PropertySet.
 void get_all_properties(int how_many, PropertiesHolder nproperties, PropertiesIteratorHolder rest)
          Returns all of the properties defined in the PropertySet.
 void get_all_property_names(int how_many, PropertyNamesHolder property_names, PropertyNamesIteratorHolder rest)
          Returns all of the property names currently defined in the PropertySet.
 void get_allowed_properties(PropertyDefsHolder property_defs)
          Indicates which properties are supported by this PropertySet.
 void get_allowed_property_types(PropertyTypesHolder property_types)
          Indicates which types of properties are supported by this PropertySet.
 int get_number_of_properties()
          Returns the current number of properties associated with this PropertySet.
 boolean get_properties(java.lang.String[] property_names, PropertiesHolder nproperties)
          Returns the values of the properties listed in property_names.
 PropertyModeType get_property_mode(java.lang.String property_name)
          Returns the mode of the property in the PropertySet.
 boolean get_property_modes(java.lang.String[] property_names, PropertyModesHolder property_modes)
          Returns the modes of the properties listed in property_names.
 org.omg.CORBA.Any get_property_value(java.lang.String property_name)
          Returns the value of a property in the PropertySet.
 boolean is_property_defined(java.lang.String property_name)
          The is_property_defined operation returns true if the property is defined in the PropertySet, and returns false otherwise.
 void set_property_mode(java.lang.String property_name, PropertyModeType property_mode)
          Sets the mode of a property in the PropertySet.
 void set_property_modes(PropertyMode[] property_modes)
          Sets the mode for each property in the property_modes parameter.
 
Methods inherited from class org.omg.CosPropertyService.PropertySetDefPOA
_all_interfaces, _invoke, _this, _this
 
Methods inherited from class org.omg.PortableServer.Servant
_default_POA, _get_delegate, _get_interface_def, _is_a, _non_existent, _object_id, _orb, _poa, _set_delegate, _this_object, _this_object
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PropertySetDefImpl

public PropertySetDefImpl(org.omg.CORBA.ORB orb)
Creates a new (empty) instance of PropertySetDefImpl.

Parameters:
orb - the CORBA ORB.

PropertySetDefImpl

public PropertySetDefImpl(org.omg.CORBA.ORB orb,
                          org.omg.CORBA.TypeCode[] allowed_property_types,
                          PropertyDef[] allowed_properties)
                   throws ConstraintNotSupported
Creates a new instance of PropertySetDefImpl with the specified constraints.

Parameters:
orb - The CORBA ORB.
allowed_property_types - The list of allowed property types.
allowed_properties - The list of allowed properties.
Throws:
ConstraintNotSupported - If the type of a property in allowed_properties is not an allowed property type; as specified by allowed_property_types.

PropertySetDefImpl

public PropertySetDefImpl(org.omg.CORBA.ORB orb,
                          PropertyDef[] initial_properties)
                   throws MultipleExceptions
Creates a new instance of PropertySetDefImpl with the specified initial properties.

Parameters:
orb - the CORBA ORB.
initial_properties - the list of properties initialize this property set.
Throws:
MultipleExceptions - if an exception occurred while defining the initial properties.
Method Detail

get_allowed_property_types

public void get_allowed_property_types(PropertyTypesHolder property_types)
Indicates which types of properties are supported by this PropertySet. If the output sequence is empty, then there is no restriction on the any TypeCode portion of the property_value field of a Property in this PropertySet, unless the get_allowed_properties output sequence is not empty.

For example, a PropertySet implementation could decide to only accept properties that had any TypeCodes of tk_string and tk_ushort to simplify storage processing and retrieval.

Parameters:
property_types - the sequence of allowed property types is returned in the output parameter.

get_allowed_properties

public void get_allowed_properties(PropertyDefsHolder property_defs)
Indicates which properties are supported by this PropertySet. If the output sequence is empty, then there is no restriction on the properties that can be in this PropertySet, unless the get_allowed_property_types output sequence is not empty.

Parameters:
property_defs - the sequence of allowed properties is returned in the output parameter.

define_property_with_mode

public void define_property_with_mode(java.lang.String property_name,
                                      org.omg.CORBA.Any property_value,
                                      PropertyModeType property_mode)
                               throws InvalidPropertyName,
                                      ConflictingProperty,
                                      UnsupportedTypeCode,
                                      UnsupportedProperty,
                                      UnsupportedMode,
                                      ReadOnlyProperty
This operation will modify or add a property to the PropertySet. If the property already exists, then the property type is checked before the value is overwritten. The property mode is also checked to be sure a new value may be written. If the property does not exist, then the property is added to the PropertySet. To change the any TypeCode portion of the property_value of a property, a client must first delete_property, then invoke the define_property_with_mode.

Parameters:
property_name - the property name.
property_value - the property value.
property_mode - the property mode.
Throws:
InvalidPropertyName - Indicates that the property name is invalid (A property name of length 0 is invalid; implementations may place other restrictions oneway property names.)
ConflictingProperty - Indicates that the property indicated created a conflict in the type or value provided.
UnsupportedTypeCode - Indicates that the any TypeCode of the property_value field is not supported in this PropertySet.
UnsupportedProperty - Indicates that the supplied property is not supported in this PropertySet, either due to PropertyName restrictions or specific name-value pair restrictions.
UnsupportedMode - Indicates that the mode supplied is not supported in this PropertySet.
ReadOnlyProperty - Indicates that the property does not support client modification of the property_value field.

define_properties_with_modes

public void define_properties_with_modes(PropertyDef[] property_defs)
                                  throws MultipleExceptions
This operation will modify or add each of the properties in the Properties parameter to the PropertySet. For each property in the list, if the property already exists, then the property type is checked before overwriting the value. The property mode is also checked to be sure a new value may be written. If the property does not exist, then the property is added to the PropertySet.

This is a batch operation that returns the MultipleExceptions exception if any define operation failed.

Parameters:
property_defs - the sequence of property definitions.
Throws:
MultipleExceptions - The PropertyExceptions sequence may contain any of the exceptions that may be raised by define_property_with_mode, multiple times and in any order.

get_property_mode

public PropertyModeType get_property_mode(java.lang.String property_name)
                                   throws PropertyNotFound,
                                          InvalidPropertyName
Returns the mode of the property in the PropertySet.

Parameters:
property_name - the property name.
Throws:
PropertyNotFound - Indicates that the specified property was not defined for this PropertySet.
InvalidPropertyName - Indicates that the property name is invalid (A property name of length 0 is invalid; implementations may place other restrictions oneway property names.)

get_property_modes

public boolean get_property_modes(java.lang.String[] property_names,
                                  PropertyModesHolder property_modes)
Returns the modes of the properties listed in property_names.

When the boolean flag is true, the property_modes parameter contains valid values for all requested property names. If false, then all properties with a property_mode_type of undefined failed due to PropertyNotFound or InvalidPropertyName. A separate invocation of get_property_mode for each such property name is necessary to determine the specific exception for that property name.

This approach was taken to avoid a complex, hard to program structure to carry mixed results.

Parameters:
property_names - the sequence of property names whose modes are to be retrieved.
property_modes - the sequence of property modes retrieved is returned in the output parameter.
Returns:
true indicates that the property_modes parameter contains valid values for all requested property names. If false, then all properties with a property_mode_type of undefined failed due to PropertyNotFound or InvalidPropertyName.

set_property_mode

public void set_property_mode(java.lang.String property_name,
                              PropertyModeType property_mode)
                       throws InvalidPropertyName,
                              PropertyNotFound,
                              UnsupportedMode
Sets the mode of a property in the PropertySet.

Protection of the mode of a property is considered an implementation issue. For example, an implementation could raise the UnsupportedMode when a client attempts to change a fixed_normal property to normal.

Parameters:
property_name - the property name.
property_mode - the property mode.
Throws:
InvalidPropertyName - Indicates that the property name is invalid (A property name of length 0 is invalid; implementations may place other restrictions oneway property names.)
PropertyNotFound - Indicates that the specified property was not defined.
UnsupportedMode - Indicates that the mode supplied is not supported in this PropertySet.

set_property_modes

public void set_property_modes(PropertyMode[] property_modes)
                        throws MultipleExceptions
Sets the mode for each property in the property_modes parameter. This is a batch operation that returns the MultipleExceptions exception if any set failed.

Parameters:
property_modes - the sequence of property modes.
Throws:
MultipleExceptions - The PropertyExceptions sequence may contain any of the exceptions that may be raised by set_property_mode, multiple times and in any order.

define_property

public void define_property(java.lang.String property_name,
                            org.omg.CORBA.Any property_value)
                     throws InvalidPropertyName,
                            ConflictingProperty,
                            UnsupportedTypeCode,
                            UnsupportedProperty,
                            ReadOnlyProperty
Modifies or adds a property to the PropertySet. If the property already exists, then the property type is checked before the value is overwritten. If the property does not exist, then the property is added to the PropertySet.

To change the any TypeCode portion of the property_value of a property, a client must first delete_property, then invoke the define_property.

Parameters:
property_name - the property name.
property_value - the property value.
Throws:
InvalidPropertyName - Indicates that the property name is invalid (A property name of length 0 is invalid; implementations may place other restrictions oneway property names.)
ConflictingProperty - Indicates that the property indicated created a conflict in the type or value provided.
UnsupportedTypeCode - Indicates that the any TypeCode of the property_value field is not supported in this PropertySet.
UnsupportedProperty - Indicates that the supplied property is not supported in this PropertySet, either due to PropertyName restrictions or specific name-value pair restrictions.
ReadOnlyProperty - Indicates that the property does not support client modification of the property_value field.

define_properties

public void define_properties(Property[] nproperties)
                       throws MultipleExceptions
Modifies or adds each of the properties in Properties parameter to the PropertySet. For each property in the list, if the property already exists, then the property type is checked before overwriting the value. If the property does not exist, then the property is added to the PropertySet.

This is a batch operation that returns the MultipleExceptions exception if any define operation failed.

Parameters:
nproperties - the sequence of properties to define
Throws:
MultipleExceptions - The PropertyExceptions sequence may contain any of the exceptions that may be raised by the define_property operation, multiple times and in any order.

get_number_of_properties

public int get_number_of_properties()
Returns the current number of properties associated with this PropertySet.

Returns:
the current number of properties associated with this PropertySet.

get_all_property_names

public void get_all_property_names(int how_many,
                                   PropertyNamesHolder property_names,
                                   PropertyNamesIteratorHolder rest)
Returns all of the property names currently defined in the PropertySet. If the PropertySet contains more than how_many property names, then the remaining property names are put into the PropertyNamesIterator.

Parameters:
how_many - the number of property names to retrieve.
property_names - the sequence of property names retrieved is returned in the output parameter.
rest - the iterator to return the remaining property names.

get_property_value

public org.omg.CORBA.Any get_property_value(java.lang.String property_name)
                                     throws PropertyNotFound,
                                            InvalidPropertyName
Returns the value of a property in the PropertySet.

Parameters:
property_name - the property name.
Returns:
the property value.
Throws:
PropertyNotFound - Indicates that the specified property was not defined for this PropertySet.
InvalidPropertyName - Indicates the property name is invalid. (A property name of length 0 is invalid; implementations may place other restrictions oneway property names.)

get_properties

public boolean get_properties(java.lang.String[] property_names,
                              PropertiesHolder nproperties)
Returns the values of the properties listed in property_names.

When the boolean flag is true, the Properties parameter contains valid values for all requested property names. If false, then all properties with a value of type tk_void may have failed due to PropertyNotFound or InvalidPropertyName.

A separate invocation of get_property for each such property name is necessary to determine the specific exception or to verify that tk_void is the correct any TypeCode for that property name.

This approach was taken to avoid a complex, hard to program structure to carry mixed results.

Parameters:
property_names - the sequence of property names.
nproperties - the properties are returned in the output parameter.
Returns:
true if the Properties parameter contains valid values for all requested property names. If false, properties with a value of type tk_void may have failed due to PropertyNotFound or InvalidPropertyName.

get_all_properties

public void get_all_properties(int how_many,
                               PropertiesHolder nproperties,
                               PropertiesIteratorHolder rest)
Returns all of the properties defined in the PropertySet. If more than how_many properties are found, then the remaining properties are returned in rest.

Parameters:
how_many - the number of properties to retrieve.
nproperties - the sequence of properties retrieved is returned in the output parameter.
rest - the iterator to return the remaining properties.

delete_property

public void delete_property(java.lang.String property_name)
                     throws PropertyNotFound,
                            InvalidPropertyName,
                            FixedProperty
Deletes the specified property if it exists from a PropertySet.

Parameters:
property_name - the property name.
Throws:
PropertyNotFound - Indicates that the specified property was not defined for this PropertySet.
InvalidPropertyName - Indicates the property name is invalid. (A property name of length 0 is invalid; implementations may place other restrictions oneway property names.)
FixedProperty - Indicates that the PropertySet does not support the deletion of the specified property.

delete_properties

public void delete_properties(java.lang.String[] property_names)
                       throws MultipleExceptions
Deletes the properties defined in the property_names parameter. This is a batch operation that returns the MultipleExceptions exception if any delete failed.

Parameters:
property_names - the sequence of property names.
Throws:
MultipleExceptions - The PropertyExceptions sequence may contain any of the exceptions that may be raised by the delete_property operation, multiple times and in any order.

delete_all_properties

public boolean delete_all_properties()
Variation of delete_properties. Applies to all properties.

Since some properties may be defined as fixed property types, it may be that not all properties are deleted. The boolean flag is set to false to indicate that not all properties were deleted.

A client could invoke get_number_of_properties to determine how many properties remain. Then invoke get_all_property_names to extract the property names remaining. A separate invocation of delete_property for each such property name is necessary to determine the specific exception.

Note ? If the property is in a PropertySetDef, then the set_mode operation could be invoked to attempt to change the property mode to something other than fixed before using delete_property.

This approach was taken to avoid the use of an iterator to return an indeterminate number of exceptions.

Returns:
false if not all properties were deleted.

is_property_defined

public boolean is_property_defined(java.lang.String property_name)
                            throws InvalidPropertyName
The is_property_defined operation returns true if the property is defined in the PropertySet, and returns false otherwise.

Parameters:
property_name - the property name.
Throws:
InvalidPropertyName - Indicates the property name is invalid. (A property name of length 0 is invalid; implementations may place other restrictions oneway property names.)