Package com.iizix.urn.user

Class UserProfileStringURN

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    public class UserProfileStringURN
extends URN
implements java.lang.Cloneable, java.io.Serializable
    User Profile String Uniform Resource Naming (URN) instance class, holding various User Profile strings depending on the requested information.

    User Profile String URN's are encoded in IIZI as:

        urn:iz-pstr:id=userID[?+reload]?=query or

        urn:iz-pstr:userName=userName[?+reload]?=query

    The reload parameter is optional as will force a database request rather than using a potential cached value. The brackets around ?+reload indicates that the value is options and the brackets should not be specified. Be careful when using it too much as performance is impacted.

    The userID is a {code long} value unique to the user ID in question, the userName is a UTF-8 encoded string, and the query is the queried String, one of the names available in {@link UserProfileStringURNType} plus an additional one-based index entry when the {@link UserProfileStringURNType#multiple} flag allows it.

    Examples of query by direct String:

    • "FullName"
    • "LastName"
    • "FirstName"
    • "CompanyName"
    • "ZipCode"
    • "City"
    • "StateProvince"
    • "Country"

    Examples of the same request, but using a {@link UserProfileStringURNType}:

    • {@link UserProfileStringURNType#FullName}
    • {@link UserProfileStringURNType#LastName}
    • {@link UserProfileStringURNType#FirstName}
    • {@link UserProfileStringURNType#CompanyName}
    • {@link UserProfileStringURNType#ZipCode}
    • {@link UserProfileStringURNType#City}
    • {@link UserProfileStringURNType#StateProvince}
    • {@link UserProfileStringURNType#Country}

    Examples of query in String format when multiple values can be assigned to the query by appending "_2" to the second value, "_3" to the third value, and so on:

    • "WorkMobile<strong>_2</strong>"
    • "WorkMobile<strong>_3</strong>"
    • "AdditionalEmail<strong>_2</strong>"
    • "AdditionalEmail<strong>_3</strong>"
    • "AdditionalEmail<strong>_4</strong>"

    Instead of a String type of query, you can also use three parameters <i>userID</i> as a long or <i>userName</i> as a String, followed by {@link UserProfileStringURNType} and an Integer using the method {@link #fromUserID(long, UserProfileStringURNType, int)} when the userID is known, otherwise by a name String using {@link #fromUserID(String, UserProfileStringURNType, int)}:

    • <i>long_UserID</i>,{@link UserProfileStringURNType#WorkMobile},2
    • <i>long_UserID</i>,{@link UserProfileStringURNType#WorkMobile},3
    • <i>long_UserID</i>,{@link UserProfileStringURNType#AdditionalEmail},2
    • <i>long_UserID</i>,{@link UserProfileStringURNType#AdditionalEmail},3
    • <i>long_UserID</i>,{@link UserProfileStringURNType#AdditionalEmail},4
    • <i>"BillyJean"</i>,{@link UserProfileStringURNType#WorkMobile},2
    • <i>"BillyJean"</i>,{@link UserProfileStringURNType#WorkMobile},3
    • <i>"billy.jean@something.dom"</i>,{@link UserProfileStringURNType#AdditionalEmail},2
    • <i>"billy.jean@something.dom"</i>,{@link UserProfileStringURNType#AdditionalEmail},3
    • <i>"billy.jean@something.dom"</i>,{@link UserProfileStringURNType#AdditionalEmail},4
    See Also:
    * @author Christopher Mindus, Serialized Form

    • Method Detail

      • setUserProfileStringURNProvider

        public static void setUserProfileStringURNProvider​(IUserProfileStringURNProvider provider)
        Assigns the User Profile String URN provider. This is an IIZI internal method. This method cannot only be called from the server and should not be called elsewhere.
        Throws:
        java.lang.NullPointerException - If provider is null.
        java.lang.IllegalStateException - If called twice or outside the server.

      • fromUserID

        public static UserProfileStringURN fromUserID​(long id,
                                              java.lang.String query)
        Creates a User Profile String URN using a possible cached instance of the user information.

        We recommend using the fromUserID(...) method using a {@link UserProfileStringURNType} instead of a String because it is faster.

        Parameters:
        id - The Long user ID.
        query - The query String.
        Throws:
        java.lang.IllegalArgumentException - If the id is zero.
        java.lang.NullPointerException - If query is null.
        NotFoundException - If the query String is not a valid query.

      • fromUserID

        public static UserProfileStringURN fromUserID​(long id,
                                              java.lang.String query,
                                              boolean reload)
        Creates a User Profile String URN.

        We recommend using the fromUserID(...) method using a {@link UserProfileStringURNType} instead of a String because it is faster.

        Parameters:
        id - The Long user ID.
        query - The query String.
        reload - The reload flag, false if OK to use a cached value. Be careful when setting this flag to true as it impacts performance.
        Throws:
        java.lang.IllegalArgumentException - If the id is zero.
        java.lang.NullPointerException - If query is null.
        NotFoundException - If the query String is not a valid query.

      • fromUserID

        public static UserProfileStringURN fromUserID​(long id,
                                              java.lang.String query,
                                              int oneBasedIndex)
        Creates a User Profile String URN using a possible cached instance of the user information.

        We recommend using the fromUserID(...) method using a {@link UserProfileStringURNType} instead of a String because it is faster.

        Parameters:
        id - The Long user ID.
        query - The query String.
        oneBasedIndex - The one-based index for the query if it supports it, zero otherwise.
        Throws:
        java.lang.IllegalArgumentException - If the id is zero, or if oneBasedIndex is non-zero, less than 1 or larger than 99 when the query supports multiple values.
        java.lang.NullPointerException - If query is null.
        NotFoundException - If the query String is not a valid query.

      • fromUserID

        public static UserProfileStringURN fromUserID​(long id,
                                              java.lang.String query,
                                              int oneBasedIndex,
                                              boolean reload)
                                       throws NotFoundException
        Creates a User Profile String URN.

        We recommend using the fromUserID(...) method using a {@link UserProfileStringURNType} instead of a String because it is faster.

        Parameters:
        id - The Long user ID.
        query - The query String.
        oneBasedIndex - The one-based index for the query if it supports it, zero otherwise.
        reload - The reload flag, false if OK to use a cached value. Be careful when setting this flag to true as it impacts performance.
        Throws:
        java.lang.IllegalArgumentException - If the id is zero, or if oneBasedIndex is non-zero, less than 1 or larger than 99 when the query supports multiple values.
        java.lang.NullPointerException - If query is null.
        NotFoundException - If the query String is not a valid query.

      • fromUserName

        public static UserProfileStringURN fromUserName​(java.lang.String userName,
                                                java.lang.String query)
        Creates a User Profile String URN using a possible cached instance of the user information.

        We recommend using the fromUserName(...) method using a {@link UserProfileStringURNType} instead of a String because it is faster.

        Parameters:
        userName - The User Name.
        query - The query String.
        Throws:
        java.lang.NullPointerException - If query is null.
        NotFoundException - If the query String is not a valid query.

      • fromUserName

        public static UserProfileStringURN fromUserName​(java.lang.String userName,
                                                java.lang.String query,
                                                boolean reload)
        Creates a User Profile String URN.

        We recommend using the fromUserName(...) method using a {@link UserProfileStringURNType} instead of a String because it is faster.

        Parameters:
        userName - The User Name.
        query - The query String.
        reload - The reload flag, false if OK to use a cached value. Be careful when setting this flag to true as it impacts performance.
        Throws:
        java.lang.NullPointerException - If query is null.
        NotFoundException - If the query String is not a valid query.

      • fromUserName

        public static UserProfileStringURN fromUserName​(java.lang.String userName,
                                                java.lang.String query,
                                                int oneBasedIndex)
        Creates a User Profile String URN using a possible cached instance of the user information.

        We recommend using the fromUserName(...) method using a {@link UserProfileStringURNType} instead of a String because it is faster.

        Parameters:
        userName - The User Name.
        query - The query String.
        oneBasedIndex - The one-based index for the query if it supports it, zero otherwise.
        Throws:
        java.lang.NullPointerException - If query is null.
        NotFoundException - If the query String is not a valid query.
        java.lang.IllegalArgumentException - If the oneBasedIndex is non-zero, less than 1 or larger than 99 when the query supports multiple values.

      • fromUserName

        public static UserProfileStringURN fromUserName​(java.lang.String userName,
                                                java.lang.String query,
                                                int oneBasedIndex,
                                                boolean reload)
        Creates a User Profile String URN.

        We recommend using the fromUserName(...) method using a {@link UserProfileStringURNType} instead of a String because it is faster.

        Parameters:
        userName - The User Name.
        query - The query String.
        oneBasedIndex - The one-based index for the query if it supports it, zero otherwise.
        reload - The reload flag, false if OK to use a cached value. Be careful when setting this flag to true as it impacts performance.
        Throws:
        java.lang.NullPointerException - If query is null.
        NotFoundException - If the query String is not a valid query.
        java.lang.IllegalArgumentException - If the oneBasedIndex is non-zero, less than 1 or larger than 99 when the query supports multiple values.

      • fromUserID

        public static UserProfileStringURN fromUserID​(long id,
                                              UserProfileStringURNType query)
        Creates a User Profile String URN using a possible cached instance of the user information.
        Parameters:
        id - The Long user ID.
        query - The query.
        Throws:
        java.lang.IllegalArgumentException - If the id is zero.
        java.lang.NullPointerException - If query is null.

      • fromUserID

        public static UserProfileStringURN fromUserID​(long id,
                                              UserProfileStringURNType query,
                                              boolean reload)
        Creates a User Profile String URN.
        Parameters:
        id - The Long user ID.
        query - The query.
        reload - The reload flag, false if OK to use a cached value. Be careful when setting this flag to true as it impacts performance.
        Throws:
        java.lang.IllegalArgumentException - If the id is zero.
        java.lang.NullPointerException - If query is null.

      • fromUserID

        public static UserProfileStringURN fromUserID​(long id,
                                              UserProfileStringURNType query,
                                              int oneBasedIndex)
        Creates a User Profile String URN using a possible cached instance of the user information.
        Parameters:
        id - The Long user ID.
        query - The query.
        oneBasedIndex - The one-based index for the query if it supports it, zero otherwise.
        Throws:
        java.lang.IllegalArgumentException - If the id is zero, or if oneBasedIndex is non-zero, less than 1 or larger than 99 when the query supports multiple values.
        java.lang.NullPointerException - If query is null.

      • fromUserID

        public static UserProfileStringURN fromUserID​(long id,
                                              UserProfileStringURNType query,
                                              int oneBasedIndex,
                                              boolean reload)
                                       throws NotFoundException
        Creates a User Profile String URN.
        Parameters:
        id - The Long user ID.
        query - The query.
        oneBasedIndex - The one-based index for the query if it supports it, zero otherwise.
        reload - The reload flag, false if OK to use a cached value. Be careful when setting this flag to true as it impacts performance.
        Throws:
        java.lang.IllegalArgumentException - If the id is zero, or if oneBasedIndex is non-zero, less than 1 or larger than 99 when the query supports multiple values.
        java.lang.NullPointerException - If query is null.
        NotFoundException

      • fromUserName

        public static UserProfileStringURN fromUserName​(java.lang.String userName,
                                                UserProfileStringURNType query)
        Creates a User Profile String URN using a possible cached instance of the user information.
        Parameters:
        userName - The User Name.
        query - The query.
        Throws:
        java.lang.NullPointerException - If query is null.

      • fromUserName

        public static UserProfileStringURN fromUserName​(java.lang.String userName,
                                                UserProfileStringURNType query,
                                                boolean reload)
        Creates a User Profile String URN.
        Parameters:
        userName - The User Name.
        query - The query.
        reload - The reload flag, false if OK to use a cached value. Be careful when setting this flag to true as it impacts performance.
        Throws:
        java.lang.NullPointerException - If query is null.

      • fromUserName

        public static UserProfileStringURN fromUserName​(java.lang.String userName,
                                                UserProfileStringURNType query,
                                                int oneBasedIndex)
        Creates a User Profile String URN using a possible cached instance of the user information.
        Parameters:
        userName - The User Name.
        query - The query.
        oneBasedIndex - The one-based index for the query if it supports it, zero otherwise.
        Throws:
        java.lang.NullPointerException - If query is null.
        java.lang.IllegalArgumentException - If the oneBasedIndex is non-zero, less than 1 or larger than 99 when the query supports multiple values.

      • fromUserName

        public static UserProfileStringURN fromUserName​(java.lang.String userName,
                                                UserProfileStringURNType query,
                                                int oneBasedIndex,
                                                boolean reload)
        Creates a User Profile String URN.
        Parameters:
        userName - The User Name.
        query - The query.
        oneBasedIndex - The one-based index for the query if it supports it, zero otherwise.
        reload - The reload flag, false if OK to use a cached value. Be careful when setting this flag to true as it impacts performance.
        Throws:
        java.lang.NullPointerException - If query is null.
        java.lang.IllegalArgumentException - If the oneBasedIndex is non-zero, less than 1 or larger than 99 when the query supports multiple values.

      • getURL

        public java.lang.String getURL()
        Gets the URL of this as a data URL in UTF-8 encoded data.
        Specified by:
        getURL in class URN
        Returns:
        The data URL as data:text/plain;charset=UTF-8;<i>value</i> where value is set to UTF-8 encoded "???" when "User ID" or "User Name" is not found or a database SQL exception is encountered.
        Throws:
        java.lang.IllegalStateException - If the user authentication instance is not initialized.

      • getValue

        public java.lang.String getValue​(boolean nullIfNotFound)
                          throws NotFoundException
        Gets the String result of this URN.
        Parameters:
        nullIfNotFound - Flag indicating null should be returned if true if the user value is not found, otherwise when false an empty string is returned.
        Returns:
        A String, empty or null if not found, depending on the nullIfNotFound flag.
        Throws:
        NotFoundException - If the user ID or the User Name is not found in the database, or a database error occurred.
        java.lang.IllegalStateException - If the user authentication instance is not initialized.

      • getParamString

        public java.lang.String getParamString()
        Gets the parameter string for the URN.toString() method.
        Specified by:
        getParamString in class URN
        Returns:
        The parameter string, always non-null, formatted as "userName=UserName,query=Query" or "userID=ID,query=Query" where Query is the queried enum string. If the enum string is indexed with a value between 2 and 99, ",oneBasedIndex=Index" is appended. If the request requires a reload of the user information from the database and a cached value is not acceptable, the string ",reload=true" is appended.

      • hashCode

        public int hashCode()
        Hash code of this instance.
        Specified by:
        hashCode in class URN
        Returns:
        The hash code.

      • equals

        public boolean equals​(java.lang.Object obj)
        Checks if two instances are equal.
        Specified by:
        equals in class URN
        Parameters:
        obj - The other instance.
        Returns:
        The equals flag.