sipservlet-spec
  1. sipservlet-spec
  2. SIPSERVLET_SPEC-24

Improve header support by introducing a Header interface.

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: None
    • Labels:
      None

      Description

      In 289, if you want to extract out all the headers out of a sip message you will end up writing a double for-loop to get all the headers and their values out. Also, you have to come up with your own structure for storing that information in a meaningful way. Consider the following example that extracts out all X-headers out of a message and returns them in a list:

      Example of extracting out X-headers in 289
        private List<Header> extractXHeaders(final SipServletMessage msg) {
              final Iterator<String> it = msg.getHeaderNames();
              if (it == null) {
                  return Collections.emptyList();
              }
      
              final List<Header> xHeaders = new ArrayList<Header>();
      
              while (it.hasNext()) {
                  final String header = it.next();
                  if (header.toLowerCase().startsWith("x-")) {
                      final ListIterator<String> valueIt = msg.getHeaders(header);
                      while (valueIt.hasNext()) {
                          final String value = valueIt.next();
                          xHeaders.add(new Header(header, value));
                      }
                  }
              }
      
              return xHeaders;
          }
      
      

      Not shown in the above snippet is the Header class that holds the name and the value of the header.

      Suggested solution:

      Introduce a Header interface that all headers will inherit from (in the current specification that would be Parameterable only) and expose new convenience methods in SipServletMessage for extracting out all headers.

      Note: full interface declaration at the end

      Summary of new interfaces
      Interface Header {
         String getName();
         String getValue();
      }
      
      SipServletMessage {
         ...
         Iterator<Header> getHeaders();
         ...
      }
      
      

      With the new interface additions the same code for extracting out the x-headers:

      Example of extracting out X-headers in 359 (with proposed changes)
          private List<Header> extractHeaders2(final SipServletMessage msg) {
              final Iterator<Header> headers = msg.getHeaders();
              final List<Header> xHeaders = new ArrayList<Header>();
      
              while (headers.hasNext()) {
                  final Header header = headers.next();
                  if (header.getName().toLowerCase().equals("x-")) {
                      xHeaders.add(header);
                  }
              }
      
              return xHeaders;
          }
      

      This will also allow people to create their own Header library which would have a cleaner integration with the container because of the re-usable Header-interface.

      Suggested Interface

      Suggested additions to the SipServletMessage
         public static interface SipServletMessage {
      
              /**
               * Obtain a list of all the headers in the {@link SipServletMessage}.
               * The order of the headers in the list follows that of the
               * {@link SipServletMessage}.
               * 
               * Note, modifying the iterator will not change the headers in the
               * {@link SipServletMessage}.
               * 
               * @return an iterator of all the headers in the message or an empty
               *         iterator if there are none.
               */
              Iterator<Header> getHeaders();
      
              /**
               * Returns the header with specified name. If the message did not
               * include a header of the specified name, this method returns null. If
               * multiple headers exist, the first one is returned. The header name is
               * case insensitive.
               * 
               * TODO: better name
               */
              Header getHeader2(String name);
      
              /**
               * Get all the headers with the specified name. If there are no headers
               * with that name an empty iterator will be returned. The name is case
               * insensitive.
               * 
               * @param name
               *            the name of the header to extract out of this
               *            {@link SipServletMessage}
               * @return an iterator of headers or an empty iterator if no headers
               *         with that name exists.
               */
              Iterator<Header> getHeaders2(String name);
      
              /**
               * Add a header to this message.
               * 
               * @param header
               *            the header to add to this message.
               * 
               * @throws IllegalArgumentException
               *             if the specified header field is a system header or if it
               *             cannot legally appear in this message
               */
              void addHeader(Header header) throws IllegalArgumentException;
      
              /**
               * Sets a header. If the header already has been set, the new header
               * will overwrite the previous one. If there are multiple headers with
               * the * same name, they all are replaced by this header name
               * 
               * @param header
               * @throws IllegalArgumentException
               * @throws NullPointerException
               */
              void setHeader(Header header) throws IllegalArgumentException, NullPointerException;
          }
      
      

        Activity

        No work has yet been logged on this issue.

          People

          • Assignee:
            jonbo372
            Reporter:
            jonbo372
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: