Skip navigation links

oracle.mds.cust
Class CustomizationClass

java.lang.Object
oracle.mds.cust.CustomizationClass

public abstract class CustomizationClass

extends java.lang.Object

A Customization Class (CC) evaluates the current context and the current metadata object and returns a String result to be used in customizations.

A customization class has a name, as returned by the getName() method, and a value, as returned by the getValue(RestrictedSession, MetadataObject) method. The name is combined with the value to select a customization layer to apply. For example, a UserCustomizationClass may have the name "user" and getValue() returns the current user to facilitate user customizations. Depending on the implementation, the getValue() method could return a "user" property from the context, the current database username, a user stored on the servlet session, or the OS user etc.

The Customization Class also defines a CacheHint which indicates to MDS how widely visible a metadata object with this customization will be and hence its likely duration in memory. This information may be used internally by MDS to decide whether to cache a customization and where to cache it, and any Customization Layers constructed using this CC will have this cache hint.

• Implementations should provide at most a single, parameter-less constructor.
• Implementations must not attempt to recursively load other MOs.
• Implementations must be thread-safe
• Implementations should be as efficient as possible as each registered Customization Class is re-evaluated for every call to get a MetadataObject.

The Customization Class also has a method called getIDPrefix. Components those want to generate unique id, for newly added elements as customizations, across customization layers, can use this method to get id-prefix based on the current tip customization layer name/value pair. When a new element is added as customization for a layer name/value pair, components can prefix this generated id-prefix to their actual auto generated id to make sure that their id is unique across customization layers. Please read getIDPrefix for more details.

Constructor Summary

CustomizationClass()

Method Summary

boolean	equals(java.lang.Object customizationClassObj) Checks if two CustomizationClass instances are equal.
protected java.lang.String	generateIDPrefix(oracle.mds.core.RestrictedSession mdsSession, oracle.mds.core.MetadataObject mo) This method encapsulate prefix generation logic for this customization class.
oracle.mds.naming.MOName	getBaseRef(oracle.mds.core.RestrictedSession mdsSession, oracle.mds.core.MetadataObject mo) Get the base object name relative to which the CustomizationLayer is located.
abstract oracle.mds.cust.CacheHint	getCacheHint() Get the Cache Hint for CustomizationLayers returned by this Customization Class.
java.lang.String	getIDPrefix(oracle.mds.core.RestrictedSession mdsSession, oracle.mds.core.MetadataObject mo) This method returns an ID prefix that can be used to identify a customization layer name/value pair of this customization class.
abstract java.lang.String	getName() Get the name of this customization class.
abstract java.lang.String[]	getValue(oracle.mds.core.RestrictedSession mdsSession, oracle.mds.core.MetadataObject mo) Retrieve the value(s) of this CustomizationClass based on the context and the metadata.
int	hashCode() Returns a hash code value for the object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CustomizationClass

public CustomizationClass()

Method Detail

equals

public boolean equals(java.lang.Object customizationClassObj)

Checks if two CustomizationClass instances are equal. Returns true if and only if both objects have same class, same name and same cacheHint, otherwise returns false.

Overrides:

equals in class java.lang.Object

Parameters:

customizationClassObj - another CustomizationClass instance to compare with.

Returns:

boolean - true if both are equal, false otherwise.

hashCode

public int hashCode()

Returns a hash code value for the object.

Overrides:

hashCode in class java.lang.Object

Returns:

int - hashCode of the object

getBaseRef

public final oracle.mds.naming.MOName getBaseRef(oracle.mds.core.RestrictedSession mdsSession,
                                                 oracle.mds.core.MetadataObject mo)

Get the base object name relative to which the CustomizationLayer is located.

The default implementation is to return the name of the MO passed (by MDS) into the method. This is almost always the right thing to do and we expect this default implementation will suit most clients' needs.

WARNING: this method is final at present to prevent overrides because the effects of overriding it are not yet well understood or tested. If anyone needs to override this method let us know a.s.a.p. and we will look into allowing it to be overridden. One possible such use case is to support "per instance customizations" for the OA framework.

Parameters:

mdsSession - Object giving access to certain methods on the current MDS session (MDSSession). This can be used to get information such as session properties.

mo - The base, that is, uncustomized metadata object

Returns:

A base reference for locating a Customization Layer.

getCacheHint

public abstract oracle.mds.cust.CacheHint getCacheHint()

Get the Cache Hint for CustomizationLayers returned by this Customization Class.

Returns:

CacheHint containing the customization scope.

getName

public abstract java.lang.String getName()

Get the name of this customization class. For example, calling getName() on a UserCustomizationClass might return "user".

Names need not be unique, but as the name is used with the CC value to identify a Customization Layer, CCs with non-unique names should be used with a single MO with caution.

Returns:

The name of this customization class.

getValue

public abstract java.lang.String[] getValue(oracle.mds.core.RestrictedSession mdsSession,
                                            oracle.mds.core.MetadataObject mo)

Retrieve the value(s) of this CustomizationClass based on the context and the metadata. For example, calling getValue() on a UserCustomizationClass might return an array with single entry "johnsmith".

Most implementations will return null or an array with a single value. A null value or an array containing an emptry string ("") indicates there is no customization layer to apply. If the tip (last applied) customization class returns null or an array whose last element is the empty string then the metadata object is not allowed to be updated (see NoTipCustomizationLayerException).

If a non-null array is returned, implementations must ensure that all objects in the array are non-null as well. Although null values are currently handled (and ignored) this may not always be the case, and returning a single null is more efficient.

If multiple values are returned, the CustomizationLayers will be applied in the order in which they appear in the array. The last such value corresponds to the "tip" layer in case of updates made to a mutable MO obtained using this CC in the CCList.

Typical implementations will return a value based on the current execution context for the current user, pulled either from static or thread local state maintained by the client, or from properties set (by the client) on the MDS session.

For customization documents stored on a file system, the value will refer to a potential directory, so care should be taken not to exceed any file system limitations on the length of directory names (e.g. 255 bytes on most Linux or Unix systems). Bear in mind also that if any of the characters included in the return value are not valid Java identifier characters, they will be encoded when converted into a customization directory name. This encoding comprises a prefix plus a hexadecimal String representation of the character. A 16-bit character will be encoded as three characters, e.g. "%0f", and a 32-bit character will be encoded as six characters, e.g. "%u0a3f". It is important that such expansion of the value returned by a CustomizationClass will not exceed a file system directory name limit.

Parameters:

mdsSession - Object giving access to certain methods on the current MDS session (MDSSession). This can be used to get information such as session properties.

mo - The base, that is, uncustomized metadata object

Returns:

A String array of values for this class, null if no values are to be returned.

getIDPrefix

public final java.lang.String getIDPrefix(oracle.mds.core.RestrictedSession mdsSession,
                                          oracle.mds.core.MetadataObject mo)
                                   throws oracle.mds.naming.InvalidReferenceException

This method returns an ID prefix that can be used to identify a customization layer name/value pair of this customization class. The ID prefix returned by this method is a valid MDS ID.

Implementations of CustomizationClass should override the protected generateIDPrefix method to return a suitable ID prefix for the customization layers corresponding to their implementations. Implementors of generateIDPrefix should ensure to follow the rules laid down for MDS ID while generating the prefixes as the value returned by the generateIDPrefix method is always validated against these rules. Failure to adhere to these rules will result in an exception.

If CustomizationClass providers have additional validation requirements then they should validate the ID prefix returned by the getIDPrefix method. At the minimum the value returned by the getIDPrefix method is always as valid MDS ID.

Parameters:

mdsSession - RestrictedSession

mo - MetadataObject.

Returns:

A String value which will be used as the prefix when generating unique identifiers for inserted elements.

Throws:

oracle.mds.naming.InvalidReferenceException - if id-prefix returned by generateIDPrefix() contains invalid characters for a unique identifer.

generateIDPrefix

protected java.lang.String generateIDPrefix(oracle.mds.core.RestrictedSession mdsSession,
                                            oracle.mds.core.MetadataObject mo)

This method encapsulate prefix generation logic for this customization class. A customization layer corresponds to a particular name and value, as returned by the getName and getValue methods.

For example, a country customization class CountryCC might return name "country" and values "us", "uk", "cz", etc, giving customization layers (country, us), (country,uk), etc. The default implementation of this method return the name concatenated with the value as prefix.

This method may need to be overridden for two reasons:

1. For performance reasons, customization classes which are used with ADF applications should ensure this method returns values as short as possible (ideally 4 characters or less). For this they will need to override this method.
2. To ensure generated identifiers for inserted elements do not conflict between customization layers, implementations of this method should be careful to ensure that the prefixes returned for the customization layers which are applied when getting a MetadataObject are always different. Otherwise errors may result, including DuplicateRefException failures at runtime (error MDS-00010).

The requirements here are as follows:

1. Prefixes for different customization classes should be unique. This is satisfied by simply returning shortened form of name & value provided this resultant string is unique across all the customization classes being used. Example: two CustomizationClasses are used when fetching a MetadataObject: CountryCC and UserCC. CountryCC's getName and getValue methods return values "country" and "uk", UserCC returns "user", "Fred". This means the applied customization layers are (country,uk) and (user,fred). Let's say each layer inserts a push button <prefix>btn1, where <prefix> is the value returned by this method. If the two customization classes return different prefixes, for example, "country" and "user", then the id's for that are inserted elements will be different ("countybtn1 and "userbtn1", so there is no conflict. However, if both customization classes would return the same prefix ("p" for example), the elements would have the same ID ("pbtn1"), resulting in an error.
2. Customization classes whose layers are swappable need to definitely include the value (or a shortened form of it) in their prefixes. Swappable means the customization class may return different values at different times for the same user for the same metadata object, and it is not the tip class (meaning customization layers from other customization classes may be applied on top).

Example 1 (non-tip customization class with swappable layouts) The same customization classes are used as in the previous example (CountryCC and UserCC). (user,Fred) customizations can be applied on top of either (country,uk) layer or (country,us), that is, the country customization class has swappable layers. An "OK" button is inserted by the (country,uk) layer and a "Cancel" button is inserted by (country,us). The suffix portion of the id will be "btn1" in both cases, assuming it's the first button in each layer. The inserted "OK" button from the (country,uk) layer is customized by the (user,Fred) layer to change the label from "OK" to "Apply". Unintended behavior will result if the layerID for both country layers is just "country", because both inserted buttons will have id="countrybtn1". So when we apply the user layer on top of (country,us) it will accidentally modify the inserted "Cancel" button to have label "Apply". Here is a summary of the situation:

• (country,uk): insert button label="OK" id="countrybtn1"
• (country,us): insert button label="Cancel"
• (user,nick): modify element="countrybtn1" label="Apply"

This can be remedied by overriding the generateIDPrefix method in CountryCC to return say "C" (shortened name) plus the country code, that is, "Cus", "Cuk", "Ccz", etc. The inserted buttons will then have different IDs ("Cukbtn1" and "Cusbtn1") which are still short.

Example 2 (tip customization class): Typically, the user customization class is tip, that is, it represents the last or topmost layer to be applied. Since no layers are ever applied on top of it, the situation described in example 1 cannot occur and it is therefore sufficient for getLayerID to return just the name (like "user"), or a shortened form (like "U"). It doesn't matter if inserted elements in two different user layers have the same IDs because those layers will never be applied together, and no layers will ever be applied on top of them.

The id prefix being returned by this generateIDPrefix method should always be a valid MDS ID. Anyone who overrides this method will need to make sure they always return a valid value (valid MDS ID). The returned value will be considered as valid MDS ID if it follows the following rules.

1. It should be a valid xml id.
2. The period "." is a special character in MDS-ID, it is considered as child id separator. This child separator should not occur at the beginning/ending of the value.
3. The child id separator should not occur more than once continuously.
4. It should not contain path separator character.
5. Each period (.) separated sub strings in the given value will be considered as separate child MDS IDs. So each of them should be a valid MDS ID and satisfy all the above rules.

Please see Id.isValidReference() to know more about the MDS-ID.

If the getValue() method returns multiple values for the given parameters, this default implementation of generateIDPrefix method will only consider the last layer value to generate the id prefix. If any disallowed characters (by MDS-ID) are found in the layer name concatenated with value string, those disallowed characters alone will be encoded with the '_' character in this default implementation. The child-id-separator character in the generated string will be encoded if it occurs in the following places. 1. if it occurs at the beginning/ending of the string. 2. if it occurs continuously more than once then all the periods excluding the first period "." will be encoded in each such instance. If this layer name concatenated with value string could not be encoded for a valid MDS-ID, a warning message will be logged and a string with value "null" will be returned as id-prefix.

Parameters:

mdsSession - Object giving access to certain methods on the current MDS session (MDSSession). This can be used to get information such as session properties.

mo - The base, that is, uncustomized metadata object

Returns:

A String value which will be used as the prefix when generating unique identifiers for inserted elements

Skip navigation links