org.omg.CosPropertyService
Interface PropertySetDefOperations

All Superinterfaces:
PropertySetOperations
All Known Subinterfaces:
PropertySetDef
All Known Implementing Classes:
_PropertySetDefStub, PropertySetDefImpl, PropertySetDefPOA, PropertySetDefPOATie

public interface PropertySetDefOperations
extends PropertySetOperations

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.


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_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 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.
 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.
 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 interface org.omg.CosPropertyService.PropertySetOperations
define_properties, define_property, delete_all_properties, delete_properties, delete_property, get_all_properties, get_all_property_names, get_number_of_properties, get_properties, get_property_value, is_property_defined
 

Method Detail

get_allowed_property_types

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

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

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

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

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

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

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

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.