PEP 246

Pegasus Enhancement Proposal (PEP)

PEP #: 246

Title: Language Interfaces

Status: Approved

Version History:

Version Date Author Change Description

1.0 13 February 2006 Roger Kumpf Initial Submittal

Version	Date	Author	Change Description
1.0	13 February 2006	Roger Kumpf	Initial Submittal

Abstract: The Pegasus interfaces for specifying language information are currently marked as experimental. These interfaces are proposed to be released into the external interface set.

Definition of the Problem

Providers and clients need to include language information in CIM requests and responses to meet localization requirements. The mechanisms are available to do this, but the interfaces are experimental. These interfaces need to be made available to clients and providers that have compatibility requirements.

Proposed Solution

The language interfaces affected by this proposal are in these files:

Pegasus/Common/LanguageTag.h
Pegasus/Common/AcceptLanguageList.h
Pegasus/Common/ContentLanguageList.h
Pegasus/Common/OperationContext.h
Pegasus/Common/ResponseHandler.h
Pegasus/Client/CIMClient.h

The specific changes associated with this proposal are to remove the PEGASUS_USE_EXPERIMENTAL_INTERFACES preprocessor directives surrounding these interfaces and to remove the "Experimental Interface" designations from the associated doc++ documentation.

LanguageTag.h

The LanguageTag class models the basic unit of language specification, based on RFC 3066 (and ultimately RFC 3066bis).

/** Experimental Interface

    This class specifies a language in a standard form (based on RFC 3066),
    including the special language range "*".  Note:  This class may be
    extended to support RFC 3066bis in the future.
 */
class PEGASUS_COMMON_LINKAGE LanguageTag
{
public:

    /**
        Constructs an uninitialized LanguageTag object.  A method
        invocation on an uninitialized LanguageTag object will
        result in the throwing of an UninitializedObjectException.  An
        uninitialized object may be converted into an initialized object only
        by using the assignment operator with an initialized object.
     */
    LanguageTag();

    /**
        Constructs a LanguageTag object from a language tag String.
        The syntax of the language tag String is validated, but the subtags
        are not verified to be values registered with ISO or IANA.
        @param languageTag A String containing a language tag (for example,
        "en-US").
        @exception Exception if the syntax of the language tag String is not
        valid.
     */
    LanguageTag(const String& languageTagString);

    /**
        Copy constructor.
        @param languageTag The LanguageTag object to copy.
     */
    LanguageTag(const LanguageTag& languageTag);

    /**
        Destructor.
     */
    ~LanguageTag();

    /**
        Assignment operator.
        @param languageTag The LanguageTag object to copy.
     */
    LanguageTag& operator=(const LanguageTag& languageTag);

    /**
        Gets the language value, if present.
        @return A String containing the language value for this LanguageTag
        object if the primary subtag is two or three characters in length,
        an empty String otherwise.
        @exception UninitializedObjectException if the LanguageTag
        has not been initialized.
     */
    String getLanguage() const;

    /**
        Gets the country code from the second subtag, if present.
        @return A String containing the country code for this LanguageTag
        object if the primary subtag is two or three characters in length
        and the second subtag is two characters in length, an empty String
        otherwise.
        @exception UninitializedObjectException if the LanguageTag
        has not been initialized.
     */
    String getCountry() const;

    /**
        Gets the language variant, if applicable.  The language variant
        includes all the subtags after the country code (if present) or
        language value (if present).
        @return A String containing the language variant for this LanguageTag
        object if the primary subtag is two or three characters in length,
        an empty String otherwise.
        @exception UninitializedObjectException if the LanguageTag
        has not been initialized.
     */
    String getVariant() const;

    /**
        Returns a String representation of the language tag.
        @return A String representing the LanguageTag object in RFC 3066
        syntax (for example, "language-country-variant").
        @exception UninitializedObjectException if the LanguageTag has not
        been initialized.
     */
    String toString() const;

    /**
        Tests LanguageTag objects for equality.  Comparisons are
        case-insensitive.  Distinct but equivalent language tags are not
        considered equal.  Language range matching is not performed.
        @param languageTag A LanguageTag object to be compared.
        @return True if the language tags differ only in case, false otherwise.
        @exception UninitializedObjectException if either of the
        LanguageTags has not been initialized.
     */
    Boolean operator==(const LanguageTag& languageTag) const;

    /**
        Tests LanguageTag objects for inequality.  Comparisons are
        case-insensitive.  Distinct but equivalent language tags are not
        considered equal.  Language range matching is not performed.
        @param languageTag A LanguageTag object to be compared.
        @return True if the language tags differ in more than just case,
        false otherwise.
        @exception UninitializedObjectException if either of the
        LanguageTags has not been initialized.
     */
    Boolean operator!=(const LanguageTag& languageTag) const;

private:
    LanguageTagRep* _rep;
};

AcceptLanguageList.h

The AcceptLanguageList class models a prioritized list of languages that are acceptable in a response. This class is capable of holding the value of an HTTP Accept-Language header (which is currently used in the WBEM standard), but it is not specifically tied to the HTTP protocol.

/** Experimental Interface

    This class represents an list of languages that a reader can understand
    (as may be specified in an HTTP Accept-Language header value).  It is
    managed as a prioritized list of LanguageTag objects and quality values.
 */
class PEGASUS_COMMON_LINKAGE AcceptLanguageList
{
public:

    /**
        Constructs an empty AcceptLanguageList object.
     */
    AcceptLanguageList();

    /**
        Copy constructor.
        @param acceptLanguages The AcceptLanguageList object to copy.
     */
    AcceptLanguageList(const AcceptLanguageList& acceptLanguages);

    /**
        Destructor.
     */
    ~AcceptLanguageList();

    /**
        Assignment operator.
        @param acceptLanguages The AcceptLanguageList object to copy.
     */
    AcceptLanguageList& operator=(const AcceptLanguageList& acceptLanguages);

    /**
        Returns the number of LanguagesTags in the AcceptLanguageList object.
        @return Integer size of the AcceptLanguageList list.
     */
    Uint32 size() const;

    /**
        Accesses an LanguageTag at a specified index.
        @param index Integer index of the LanguageTag to access.
        Valid indices range from 0 to size()-1.
        @return The LanguageTag corresponding to the specified index.
        @exception IndexOutOfBoundsException If the specified index is out of
        range.
     */
    LanguageTag getLanguageTag(Uint32 index) const;

    /**
        Accesses a quality value at a specified index (corresponding to a
        language tag).
        @param index Integer index of the quality value to access.
        Valid indices range from 0 to size()-1.
        @return The quality value corresponding to the specified index.
        @exception IndexOutOfBoundsException If the specified index is out of
        range.
     */
    Real32 getQualityValue(Uint32 index) const;

    /**
        Inserts a LanguageTag and quality value into the AcceptLanguageList
        object.  The element is inserted in order of descending quality value
        and after any other elements with the same quality value.
        @param languageTag The LanguageTag to insert.
        @param qualityValue The quality value to insert.
     */
    void insert(
        const LanguageTag& languageTag,
        Real32 qualityValue);

    /**
        Removes the specified LanguageTag and quality value from the 
        AcceptLanguageList object.
        @param index Integer index of the element to remove.
        @exception IndexOutOfBoundsException If the specified index is out of
        range.
     */
    void remove(Uint32 index);

    /**
        Finds the first occurrence of the specified LanguageTag in the
        AcceptLanguageList object and returns its index.
        @param languageTag The LanguageTag to find.
        @return Integer index of the element, if found; otherwise
        PEG_NOT_FOUND.
     */
    Uint32 find(const LanguageTag& languageTag) const;

    /**
        Removes all the LanguageTags and quality values from the
        AcceptLanguageList object.
     */
    void clear();

    /**
        Tests AcceptLanguageList objects for equality.
        @param acceptLanguages An AcceptLanguageList object to be compared.
        @return True if the AcceptLanguageList objects contain the same
        LanguageTags and quality values in the same order, false otherwise.
     */
    Boolean operator==(const AcceptLanguageList& acceptLanguages) const;

    /**
        Tests AcceptLanguageList objects for inequality.
        @param acceptLanguages An AcceptLanguageList object to be compared.
        @return False if the AcceptLanguageList objects contain the same
        LanguageTags and quality values in the same order, true otherwise.
     */
    Boolean operator!=(const AcceptLanguageList& acceptLanguages) const;

private:
    AcceptLanguageListRep* _rep;
};

ContentLanguageList.h

The ContentLanguageList class models a list of languages, which is generally used to indicate the languages in accompanying data (such as a CIM response). This class is capable of holding the value of an HTTP Content-Language header (which is currently used in the WBEM standard), but it is not specifically tied to the HTTP protocol.

/** Experimental Interface

    This class represents a list of content languages (such as may appear
    in an HTTP Content-Language header value).  It is managed as a list of
    LanguageTag objects.
 */
class PEGASUS_COMMON_LINKAGE ContentLanguageList
{
public:

    /**
        Constructs an empty ContentLanguageList object.
     */
    ContentLanguageList();

    /**
        Copy constructor.
        @param contentLanguages The ContentLanguageList object to copy.
     */
    ContentLanguageList(const ContentLanguageList& contentLanguages);

    /**
        Destructor.
     */
    ~ContentLanguageList();

    /**
        Assignment operator.
        @param contentLanguages The ContentLanguageList object to copy.
     */
    ContentLanguageList& operator=(const ContentLanguageList& contentLanguages);

    /**
        Returns the number of LanguageTags in the ContentLanguageList object.
        @return Integer size of the ContentLanguageList list.
     */
    Uint32 size() const;

    /**
        Accesses a LanguageTag at a specified index.
        @param index Integer index of the LanguageTag to access.
        Valid indices range from 0 to size()-1.
        @return The LanguageTag corresponding to the specified index.
        @exception IndexOutOfBoundsException If the specified index is out of
        range.
     */
    LanguageTag getLanguageTag(Uint32 index) const;

    /**
        Appends a LanguageTag to the ContentLanguageList object.
        @param languageTag The LanguageTag to append.
     */
    void append(const LanguageTag& languageTag);

    /**
        Removes the specified LanguageTag from the ContentLanguageList object.
        @param index Integer index of the LanguageTag to remove.
        @exception IndexOutOfBoundsException If the specified index is out of
        range.
     */
    void remove(Uint32 index);

    /**
        Finds the specified LanguageTag in the ContentLanguageList object and
        returns its index.
        @param languageTag The LanguageTag to find.
        @return Integer index of the LanguageTag, if found; otherwise
        PEG_NOT_FOUND.
     */
    Uint32 find(const LanguageTag& languageTag) const;

    /**
        Removes all the LanguageTags from the ContentLanguageList object.
     */
    void clear();

    /**
        Tests ContentLanguageList objects for equality.
        @param contentLanguages A ContentLanguageList object to be compared.
        @return True if the ContentLanguageList objects contain the same
        LanguageTags in the same order, false otherwise.
     */
    Boolean operator==(const ContentLanguageList& contentLanguages) const;

    /**
        Tests ContentLanguageList objects for inequality.
        @param contentLanguages A ContentLanguageList object to be compared.
        @return False if the ContentLanguageList objects contain the same
        LanguageTags in the same order, true otherwise.
     */
    Boolean operator!=(const ContentLanguageList& contentLanguages) const;

private:
    ContentLanguageListRep *_rep;
};

OperationContext.h

The AcceptLanguageListContainer and ContentLanguageListContainer classes allow an AcceptLanguageList and a ContentLanguageList, respectively, to be included in an OperationContext. These are necessary for a provider to get the language information that is required for localization.

/** Experimental Interface

    An AcceptLanguageListContainer object holds a list of languages that
    are acceptable in the response for a given operation.
*/
class PEGASUS_COMMON_LINKAGE AcceptLanguageListContainer
    : virtual public OperationContext::Container
{
public:
    /**
        The unique name for this container type.
    */
    static const String NAME;

    /**
        Constructs an AcceptLanguageListContainer object from the
        specified Container.
        @param container The Container object to copy.
        @exception DynamicCastFailedException If the specified Container
        object is not an AcceptLanguageListContainer object.
    */
    AcceptLanguageListContainer(
        const OperationContext::Container& container);

    /**
        Constructs a copy of the specified AcceptLanguageListContainer.
        @param container The AcceptLanguageListContainer object to copy.
    */
    AcceptLanguageListContainer(
        const AcceptLanguageListContainer& container);

    /**
        Constructs an AcceptLanguageListContainer with the specified
        accept language list.
        @param languages An AcceptLanguageList with the response languages
        that are acceptable in this context.
    */
    AcceptLanguageListContainer(const AcceptLanguageList& languages);
    
    /**
        Destructs the AcceptLanguageListContainer.
    */
    virtual ~AcceptLanguageListContainer();

    /**
        Assigns the value of the specified AcceptLanguageListContainer
        object to this object.
        @param container The AcceptLanguageListContainer object to copy.
    */
    AcceptLanguageListContainer& operator=(
        const AcceptLanguageListContainer& container);

    /**
        Returns the unique name for this Container type.
        @return The String name of the Container type.
    */
    virtual String getName() const;

    /**
        Makes a copy of this AcceptLanguageListContainer object.  The caller
        is responsible for cleaning up the copy by calling destroy() method.
        @return A pointer to the new Container object.
    */
    virtual OperationContext::Container* clone() const;

    /**
        Cleans up an AcceptLanguageListContainer object that was created by
        the clone() method.
    */
    virtual void destroy();

    /**
        Gets the list of acceptable response languages from the
        AcceptLanguageListContainer.
        @return An AcceptLanguageList with the response languages that are
        acceptable in this context.
    */
    AcceptLanguageList getLanguages() const;

protected:
    AcceptLanguageListContainerRep* _rep;

private:
    AcceptLanguageListContainer();    // Unimplemented
};


/** Experimental Interface

    A ContentLanguageListContainer object holds a list of languages that
    are contained in the associated data.
*/
class PEGASUS_COMMON_LINKAGE ContentLanguageListContainer
    : virtual public OperationContext::Container
{
public:

    /**
        The unique name for this container type.
    */
    static const String NAME;

    /**
        Constructs a ContentLanguageListContainer object from the
        specified Container.
        @param container The Container object to copy.
        @exception DynamicCastFailedException If the specified Container
        object is not a ContentLanguageListContainer object.
    */
    ContentLanguageListContainer(
        const OperationContext::Container& container);

    /**
        Constructs a copy of the specified ContentLanguageListContainer.
        @param container The ContentLanguageListContainer object to copy.
    */
    ContentLanguageListContainer(
        const ContentLanguageListContainer& container);

    /**
        Constructs a ContentLanguageListContainer with the specified
        content language list.
        @param languages A ContentLanguageList with the languages that are
        contained in the associated data.
    */
    ContentLanguageListContainer(const ContentLanguageList& languages);

    /**
        Destructs the ContentLanguageListContainer.
    */
    virtual ~ContentLanguageListContainer();

    /**
        Assigns the value of the specified ContentLanguageListContainer
        object to this object.
        @param container The ContentLanguageListContainer object to copy.
    */
    ContentLanguageListContainer& operator=(
        const ContentLanguageListContainer& container);

    /**
        Returns the unique name for this Container type.
        @return The String name of the Container type.
    */
    virtual String getName() const;

    /**
        Makes a copy of this ContentLanguageListContainer object.  The caller
        is responsible for cleaning up the copy by calling destroy() method.
        @return A pointer to the new Container object.
    */
    virtual OperationContext::Container* clone() const;

    /**
        Cleans up a ContentLanguageListContainer object that was created
        by the clone() method.
    */
    virtual void destroy();

    /**
        Gets the list of content languages from the
        ContentLanguageListContainer.
        @return A ContentLanguageList with the languages that are contained
        in the associated data.
    */
    ContentLanguageList getLanguages() const;

protected:
    ContentLanguageListContainerRep* _rep;

private:
    ContentLanguageListContainer();    // Unimplemented
};

ResponseHandler.h

The ResponseHandler::setContext() method allows a provider to specify the language information associated with the information it delivers.


    /** Experimental Interface

        Sets the context for operation responses delivered to the CIM Server.
        This method allows a provider to communicate context information
        (such as content language) along with an operation response.  The
        context information applies to all the operation response data
        delivered to this ResponseHandler object.  The context information
        is applied at the time the complete() method is called.
    */
#ifdef PEGASUS_OS_OS400
virtual
#endif
    void setContext(const OperationContext & context);

CIMClient.h

Several methods in the CIMClient interface allow a client application to specify its language preferences and the languages used in the data it sends, as well as to retrieve the languages associated with response data.


    /** Experimental Interface

        Configures the accept languages to be specified on subsequent
        requests from this client.  Accept languages are the preferred
        languages for response data.
        @param langs An AcceptLanguageList object specifying the languages
        preferred by this client.
    */
    void setRequestAcceptLanguages(const AcceptLanguageList& langs);

    /** Experimental Interface

        Gets the accept languages currently configured for this client.
        Accept languages are the preferred languages for response data.
        @return An AcceptLanguageList object specifying the preferred languages
        configured for this client.
    */
    AcceptLanguageList getRequestAcceptLanguages() const;

    /** Experimental Interface

        Configures the content languages to be specified on subsequent
        requests from this client.  The content languages indicate the
        languages associated with request data sent from this client.
        @param langs A ContentLanguageList object specifying the languages
        associated with this client's request data.
    */
    void setRequestContentLanguages(const ContentLanguageList& langs);

    /** Experimental Interface

        Gets the content languages currently configured for this client.
        The content languages indicate the languages associated with request
        data sent from this client.
        @return A ContentLanguageList object specifying the languages used in
        request data from this client.
    */
    ContentLanguageList getRequestContentLanguages() const;

    /** Experimental Interface

        Gets the content languages of the last response received by this
        client.  The content languages indicate the languages associated
        with the data included in the response.
        @return A ContentLanguageList object specifying the languages used in
        the last response received by this client.
    */
    ContentLanguageList getResponseContentLanguages() const;

Test Plan

These interfaces are already tested extensively in the automated test suite, with nearly 100% code coverage.

Schedule

Action Planned Actual Comment

PEP Submitted 2/13/06 2/13/06

PEP Reviewed 2/28/06 2/28/06

PEP Approved 3/17/06 3/7/06

Code Committed Pegasus 2.6 4/18/06

Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.; EMC Corporation; Symantec Corporation; The Open Group.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Template last modified: March 9th 2004 by Martin Kirk
Template version: 1.8

Action	Planned	Actual	Comment
PEP Submitted	2/13/06	2/13/06
PEP Reviewed	2/28/06	2/28/06
PEP Approved	3/17/06	3/7/06
Code Committed	Pegasus 2.6	4/18/06