com.ibm.twss.common.siputils.pheader
Class PChargingVector

java.lang.Object
  extended by com.ibm.twss.common.siputils.pheader.PChargingVector

public class PChargingVector
extends java.lang.Object

Utilty to add/modify P-Charging-Vector headers. These headers allow IMS signaling elements to generate/query IMS Charging IDs (icid) and originating and terminating Inter Operator Identifiers (ioi). Follows 3GPP TS 24.229 and RFC 3455. Note that the PChargingVector class is intended for use with UAC and UAS (User Agent Client or Server) and not a Proxy. The PChargingVector utility is used to keep track of and query information related to the session state. It must be called during all signally events, in a manner similar to this:

PChargingVector.piggybackOnto(ack,ioi);

Version:
1.2

Field Summary
static java.lang.String HEADER
          The SIP header string for a P-Charging-Vector header
static java.lang.String PARAM_ICID_GENERATED_AT
          The icid-generated-at parameter name
static java.lang.String PARAM_ICID_VALUE
          The icid-value parameter name
static java.lang.String PARAM_ORIG_IOI
          The orig-ioi parameter name
static java.lang.String PARAM_TERM_IOI
          The term-ioi parameter name
 
Method Summary
static java.lang.String generateIcidGeneratedAt()
          Retrieve this system's IP address for use in a P-Charging-Vector icid-generated-at parameter.
static java.lang.String generateIcidValue(javax.servlet.sip.SipServletMessage msg)
          Deterministically generate an IMS Charging ID (icid) suitable for use in a P-Charging-Vector header.
static java.lang.String getIcidGeneratedAt(java.lang.CharSequence charSeq)
          Retrieves the RFC 3455-defined icid-generated-at parameter from the given character sequence.
static java.lang.String getIcidValue(java.lang.CharSequence charSeq)
          Retrieves the RFC 3455-defined icid-value parameter from the given character sequence.
static java.lang.String getOrigIOI(java.lang.CharSequence charSeq)
          Retrieves the RFC 3455-defined orig-ioi parameter from the given character sequence.
static java.lang.String getTermIOI(java.lang.CharSequence charSeq)
          Retrieves the RFC 3455-defined term-ioi parameter from the given character sequence.
static boolean isValidIcidGeneratedAt(java.lang.CharSequence charSeq)
          Checks if the entire character sequence is a valid icid-gen-addr value per RFC 3455 page 26.
static boolean isValidIcidValue(java.lang.CharSequence charSeq)
          Checks if the entire character sequence is a valid IMS Charging ID (icid) value per RFC 3455 page 26.
static boolean isValidIOI(java.lang.CharSequence charSeq)
          Checks if the entire character sequence is a valid inter operator identifier (ioi) per RFC 3455 page 26.
static java.lang.String piggybackOnto(javax.servlet.sip.SipServletMessage msg, java.lang.String ioi)
          Perform the processing necessary to have P-Charging-Vector functionality piggyback atop a regular SIP dialog using the given Inter Operator Identifier (ioi).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

HEADER

public static final java.lang.String HEADER
The SIP header string for a P-Charging-Vector header

See Also:
Constant Field Values

PARAM_ICID_VALUE

public static final java.lang.String PARAM_ICID_VALUE
The icid-value parameter name

See Also:
Constant Field Values

PARAM_ICID_GENERATED_AT

public static final java.lang.String PARAM_ICID_GENERATED_AT
The icid-generated-at parameter name

See Also:
Constant Field Values

PARAM_ORIG_IOI

public static final java.lang.String PARAM_ORIG_IOI
The orig-ioi parameter name

See Also:
Constant Field Values

PARAM_TERM_IOI

public static final java.lang.String PARAM_TERM_IOI
The term-ioi parameter name

See Also:
Constant Field Values
Method Detail

isValidIOI

public static boolean isValidIOI(java.lang.CharSequence charSeq)
Checks if the entire character sequence is a valid inter operator identifier (ioi) per RFC 3455 page 26. Values for which this method returns true are suitable for use in P-Charging-Vector orig-ioi and term-ioi parameters.

Parameters:
charSeq - to check.
Returns:
True if the character sequence is a valid ioi, false otherwise. Returns false on null input.

isValidIcidValue

public static boolean isValidIcidValue(java.lang.CharSequence charSeq)
Checks if the entire character sequence is a valid IMS Charging ID (icid) value per RFC 3455 page 26. Values for which this method returns true are suitable for use in P-Charging-Vector icid-value parameters.

Parameters:
charSeq - to check.
Returns:
True if the character sequence is a valid icid-value, false otherwise. Returns false on null input.

generateIcidValue

public static java.lang.String generateIcidValue(javax.servlet.sip.SipServletMessage msg)
                                          throws java.lang.NullPointerException
Deterministically generate an IMS Charging ID (icid) suitable for use in a P-Charging-Vector header. The icid is generated from the application session id, the session id, and the creation times of both session objects. These sources have the advantages of being a globally unique combination of data, easy to access for any SipServletMessage, not depending on values from incoming network message contents, and being deterministic for any SipServletMessage within a SIP dialog.

Parameters:
msg - to use for information when generating the value
Returns:
an RFC 3261 token for use in a P-Charging-Vector's icid-value parameter.
Throws:
java.lang.NullPointerException - if msg == null.
java.lang.IllegalStateException - if either the message's SipSession or SipApplicationSession instance are invalid.

isValidIcidGeneratedAt

public static boolean isValidIcidGeneratedAt(java.lang.CharSequence charSeq)
Checks if the entire character sequence is a valid icid-gen-addr value per RFC 3455 page 26. Values for which this method returns true are suitable for use in P-Charging-Vector icid-generated-at parameters.

Parameters:
charSeq - to check.
Returns:
True if the character sequence is a valid icid-gen-addr, false otherwise. Returns false on null input.

generateIcidGeneratedAt

public static java.lang.String generateIcidGeneratedAt()
Retrieve this system's IP address for use in a P-Charging-Vector icid-generated-at parameter.

Returns:
a String representation that follows RFC 3261's host rule.

getIcidValue

public static java.lang.String getIcidValue(java.lang.CharSequence charSeq)
Retrieves the RFC 3455-defined icid-value parameter from the given character sequence. If character sequence contains multiple, valid icid-value parameters, the first one is returned.

Parameters:
charSeq - to check.
Returns:
the contents of an icid-value parameter, if found. Returns null if no well-formed icid-value is present, and null on null input.

getIcidGeneratedAt

public static java.lang.String getIcidGeneratedAt(java.lang.CharSequence charSeq)
Retrieves the RFC 3455-defined icid-generated-at parameter from the given character sequence. If character sequence contains multiple, valid icid-generated-at parameters, the first one is returned.

Parameters:
charSeq - to check.
Returns:
the contents of an icid-generated-at parameter, if found. Returns null if no well-formed icid-generated-at is present, and null on null input.

getOrigIOI

public static java.lang.String getOrigIOI(java.lang.CharSequence charSeq)
Retrieves the RFC 3455-defined orig-ioi parameter from the given character sequence. If character sequence contains multiple, valid orig-ioi parameters, the first one is returned.

Parameters:
charSeq - to check.
Returns:
the contents of an orig-ioi parameter, if found. Returns null if no well-formed orig-ioi is present, and null on null input.

getTermIOI

public static java.lang.String getTermIOI(java.lang.CharSequence charSeq)
Retrieves the RFC 3455-defined term-ioi parameter from the given character sequence. If character sequence contains multiple, valid term-ioi parameters, the first one is returned.

Parameters:
charSeq - to check.
Returns:
the contents of a term-ioi parameter, if found. Returns null if no well-formed term-ioi is present, and null on null input.

piggybackOnto

public static java.lang.String piggybackOnto(javax.servlet.sip.SipServletMessage msg,
                                             java.lang.String ioi)
Perform the processing necessary to have P-Charging-Vector functionality piggyback atop a regular SIP dialog using the given Inter Operator Identifier (ioi). This method hides the necessary state/logic from application developers. Every incoming SipServletMessage should be passed to this method before the application finishes servicing it, and every outgoing SipServletMessage should be passed to this method before the application sends it. Both final (2xx-6xx) and non-final (1xx) responses must be passed to this method. The method is a NOP if the given ioi is either null or contains only whitespace. The method does NOT ensure that the ioi is well-formed; callers are encouraged to use isValidIOI(...) to do so. Note that isValidIOI(...) will return false on ioi parameters that cause this method to be a NOP. The method requires that external locking prevents two messages in the same SIP dialog from being processed simultaneously. The logic follows 3GPP TS 24.229 version 6.11.0 sections 5.7.2 and 5.7.3 along with RFC 3455.

Parameters:
msg - to update or use for any necessary P-Charging-Vector info.
ioi - to use in orig-ioi and term-ioi headers.
Returns:
the current P-Charging-Vector in use for the SipServletMessage's dialog; Null indicates that no P-Charging-Vector is in use on this dialog.
See Also:
isValidIOI(CharSequence)


Copyright © 2003 IBM Corp. All Rights Reserved.