message.java

jxta平台的开发包

     *  in which they were added to the Message.
     *
     *  <p/>The iterator returned is not synchronized with the message and will
     *  throw {@link java.util.ConcurrentModificationException} if the
     *  message is modified.
     *
     *  @param namespace contains the namespace which must be matched in the
     *  elements returned. You can specify null as a shorthand for the default
     *  namespace.
     *  @param name contains the name of the elements to get
     *  @return Enumeration of Elements.
     *
     **/
    public ElementIterator getMessageElements( String namespace, String name ) {
        List theMsgElements = new ArrayList( elements.size() );
        
        if( null == namespace ) {
            namespace = getDefaultNamespace();
        }
        
        Iterator eachElement = elements.iterator();
        
        while ( eachElement.hasNext() ) {
            element anElement = (element) eachElement.next();
            
            if( namespace.equals(anElement.namespace) && name.equals(anElement.element.getElementName()) ) {
                theMsgElements.add( anElement );
            }
        }
        
        return new ElementIterator( theMsgElements.listIterator() );
    }
    
    /**
     *  Returns a list iterator of all of the elements contained in this message
     *  whose mime-type matchs the given in the order they were added to the
     *  message. Elements from all namespaces are returned.
     *
     *  <p/>The iterator returned is not synchronized with the message and will
     *  throw {@link java.util.ConcurrentModificationException} if the
     *  message is modified.
     *
     *  @param type contains the type of the elements to get
     *  @return Enumeration of Elements.
     **/
    public ElementIterator getMessageElements( MimeMediaType type ) {
        Vector theMsgElements = new Vector( elements.size() );
        
        ListIterator eachElement = elements.listIterator();
        
        while ( eachElement.hasNext() ) {
            element anElement = (element) eachElement.next();
            
            if( type.equals(anElement.element.getMimeType()) ) {
                theMsgElements.add( anElement );
            }
        }
        
        return new ElementIterator( theMsgElements.listIterator() );
    }
    
    /**
     *  Returns a list iterator of all of the elements contained in this message
     *  whose type matches the given in the order they were added to the message.
     *
     *  <p/>The iterator returned is not synchronized with the message and will
     *  throw {@link java.util.ConcurrentModificationException} if the
     *  message is modified.
     *
     *  @param namespace contains the namespace which must be matched in the
     *  elements returned. You can specify null as a shorthand for the default
     *  namespace.
     *  @param type contains the type of the elements to get
     *  @return Enumeration of Elements.
     **/
    public ElementIterator getMessageElements( String namespace, MimeMediaType type ) {
        List theMsgElements = new ArrayList( elements.size() );
        
        if( null == namespace ) {
            namespace = getDefaultNamespace();
        }
        
        Iterator eachElement = elements.iterator();
        
        while ( eachElement.hasNext() ) {
            element anElement = (element) eachElement.next();
            
            if( namespace.equals(anElement.namespace) && type.equals( anElement.element.getMimeType()) ) {
                theMsgElements.add( anElement );
            }
        }
        
        return new ElementIterator( theMsgElements.listIterator() );
    }
    
    /**
     *  Remove an the first occurance of the provided MessageElement from the
     *  message.
     *
     *  @param remove the Element to remove from the message.
     *  @return boolean returns true if the element was removed, otherwise false.
     **/
    public boolean removeMessageElement( MessageElement remove ) {
        Iterator eachElement = getMessageElements();
        
        while( eachElement.hasNext() ) {
            MessageElement anElement = (MessageElement) eachElement.next();
            
            if( remove == anElement ) {
                eachElement.remove( ); // updates mod count
                
                return true;
            }
        }
        
        return false;
    }
    
    /**
     *  Remove the first occurance of the provided MessageElement within the
     *  specified namespace from the message.  You can specify null as a
     *  shorthand for the default namespace.
     *
     *  @param namespace the namespace from which the element is to be removed.
     *  @param remove the Element to remove from the message.
     *  @return boolean returns true if the element was removed, otherwise false.
     **/
    public boolean removeMessageElement( String namespace, MessageElement remove ) {
        Iterator eachElement = getMessageElementsOfNamespace( namespace );
        
        while( eachElement.hasNext() ) {
            MessageElement anElement = (MessageElement) eachElement.next();
            
            if( remove == anElement ) {
                eachElement.remove( ); // updates mod count
        
                return true;
            }
        }
        
        return false;
    }
    
    /**
     *  Removes all of the elements in all namespaces from the message. Also
     *  clears any properties set for this message.
     **/
    public void clear() {
        elements.clear();
        namespaces.clear();
        properties.clear();
        // a cleared message has no ancestors
        lineage.retainAll( Collections.singletonList( lineage.get(0) ) );
        
        incMessageModCount();
        
        if (LOG.isEnabledFor(Level.DEBUG)) {
            LOG.debug("Cleared " + this );
        }
    }
    
    /**
     *  Returns the aggregate size of all the memeber elements.
     *
     *  @return the sum of all element sizes in bytes.
     **/
    public synchronized long getByteLength() {
        if( modCount != cachedByteLengthModCount ) {
            cachedByteLength = 0;
            Iterator eachElement = getMessageElements();
            
            while( eachElement.hasNext() ) {
                MessageElement anElement = (MessageElement) eachElement.next();
                
                cachedByteLength += anElement.getByteLength();
            }
            
            cachedByteLengthModCount = modCount;
        }
        
        return cachedByteLength;
    }
    
    /**
     *  Returns the modification count of this message. This ever ascending
     *  number can be used to determine if the message has been modified by
     *  another thread or for use in caching of parts of the message structure.
     *
     *  @return the modification count of this message.
     **/
    public int getMessageModCount() {
        return modCount;
    }
    
    /**
     *  Returns the modification count of this message. This ever ascending
     *  number can be used to determine if the message has been modified by
     *  another thread or for use in caching of parts of the message structure.
     *
     *  @return the modification count of this message.
     **/
    protected synchronized int incMessageModCount() {
        modCount++;
        
        if( LOG_MODIFICATIONS ) {
            modHistory.add( new Throwable( Long.toString(System.currentTimeMillis()) + " : " + Thread.currentThread().getName() ) );
        }
        
        if( !modifiable ) {
            IllegalStateException failure = new IllegalStateException( "Unmodifiable message should not have been modified" );
            if (LOG.isEnabledFor(Level.ERROR)) {
                LOG.error( failure, failure );
            }
            throw failure;
        }
        
        if (LOG.isEnabledFor(Level.DEBUG)) {
            LOG.debug( "Modification to " + this );
        }
        
        return modCount;
    }
    
    /**
     *  Returns a string containing the modification history for this message
     *
     *  @return a string containing the
     **/
    public synchronized String getMessageModHistory() {
        
        if( LOG_MODIFICATIONS ) {
            StringBuffer modHistoryStr = new StringBuffer( "Message Modification History for " );
            
            modHistoryStr.append( toString() );
            modHistoryStr.append( "\n\n" );
            
            for( int eachMod = modHistory.size() - 1; eachMod >= 0; eachMod-- ) {
                StringWriter aStackStr = new StringWriter();
                Throwable aStack = (Throwable) modHistory.get( eachMod );
                aStack.printStackTrace( new PrintWriter( aStackStr ) );
                
                modHistoryStr.append( "Modification #" );
                modHistoryStr.append( eachMod + 1 );
                modHistoryStr.append( ":\n\n" );
                modHistoryStr.append( aStackStr.toString() );
                modHistoryStr.append( "\n" );
            }
            
            return modHistoryStr.toString();
        } else {
            return "Modification history tracking is disabled";
        }
    }
    
    /**
     *  Returns the message number of this message. Message Numbers are intended
     *  to assist with debugging and the management of message cloning.
     *
     *  <p/>Each message is assigned a unique number upon creation. Message
     *  Numbers are monotonically increasing for each message created.
     *
     *  <p/>Message Numbers are transient, ie. if the message object is
     *  serialized then the message number after deserialization will be
     *  probably be a different value. Message numbers should not be used to
     *  record permanent relationships between messages.
     *
     *  @return int this message's message number.
     **/
    public int getMessageNumber( ) {
        return ((Integer) lineage.get( 0 )).intValue();
    }
    
    /**
     *  Returns an iterator which describes the lineage of this message. Each
     *  entry is an {@link java.lang.Integer} Message Number. The first entry is
     *  this message's number, following entries are the ancestors of this
     *  message.
     *
     *  @return an Iterator of {@link java.lang.Integer}. Each entry is a
     *  message number.
     **/
    public Iterator getMessageLineage( ) {
        return Collections.unmodifiableList(lineage).iterator();
    }
    
    /**
     *  Associate a transient property with this message. if there was a
     *  previous value for the key provided then it is returned. This feature is
     *  useful for managing the state of messages during processing and for
     *  caching. <strong>Message Properties are not transmitted as part of the
     *  Message when the message is serialized!</strong>
     *
     *  <p/>The setting of particular keys may be controlled by a Java Security
     *  Manager. Keys of type 'java.lang.Class' are checked against the caller of
     *  this method. Only callers which are instances of the key class may modify
     *  the property. This check is not possible through reflection. All other
     *  types of keys are unchecked.
     *
     *  @param key  the property key
     *  @param value  the value for the property
     *  @return previous value for the property or null if no previous
     **/
    public Object setMessageProperty( Object key, Object value ) {
        
    /*
        if( key instanceof java.lang.Class ) {
          Class keyClass = (Class) key;
          SecurityManager secure =  new SecurityManager() {
            public boolean checkCallerOfClass( Class toCheck ) {
              Class [] context = getClassContext();

              return toCheck.isAssignableFrom( context[2] );
            }
          };

          if( !secure.checkCallerOfClass( keyClass ) ) {
            throw new SecurityException( "You can't set that key from this context." );
          }
        }
     */
        
        Object res = properties.put( key, value );

        // Any property addition (including redundant) is notified. Removals are too, since
        // removal is done by assigning null.

        // Exception: when removing what was not there: no notification.

        if (!(res == null && value == null)) {
            notifyChange();
        }

        return res;
    }
    
    /**
     *  Retrieves a transient property from the set for this message.
     *
     *  @param key  the property key.
     *  @return value for the property or null if no property for this key.
     **/
    public Object getMessageProperty( Object key ) {
        
        return properties.get( key );
    }

    /**
     *  {@inheritDoc}
     **/
    public void itemChanged(SimpleSelectable o) {
        // For now, messages are not themselves registered with anything.
        // Therefore itemChanged does not do a thing.
    }
}