/* 
    P/P   *  Method: com.dmdirc.ServerStatus__static_init
          */
     1  /*
     2   * Copyright (c) 2006-2009 Chris Smith, Shane Mc Cormack, Gregory Holmes
     3   *
     4   * Permission is hereby granted, free of charge, to any person obtaining a copy
     5   * of this software and associated documentation files (the "Software"), to deal
     6   * in the Software without restriction, including without limitation the rights
     7   * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     8   * copies of the Software, and to permit persons to whom the Software is
     9   * furnished to do so, subject to the following conditions:
    10   *
    11   * The above copyright notice and this permission notice shall be included in
    12   * all copies or substantial portions of the Software.
    13   *
    14   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    15   * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    16   * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    17   * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    18   * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    19   * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    20   * SOFTWARE.
    21   */
    22  
    23  package com.dmdirc;
    24  
    25  import com.dmdirc.util.RollingList;
    26  
    27  /**
    28   * Describes the status of a server and manages transitions between different
    29   * states.
    30   *
    31   * @since 0.6.3m1
    32   * @author chris
    33   */
         /* 
    P/P   *  Method: void com.dmdirc.ServerStatus()
          * 
          *  Postconditions:
          *    this.history == &new RollingList(ServerStatus#1)
          *    this.state == &com.dmdirc.ServerState__static_init.new ServerState(ServerState__static_init#7)
          *    new RollingList(ServerStatus#1) num objects == 1
          */
    34  public class ServerStatus {
    35  
    36      /** The current state of the server. */
    37      protected ServerState state = ServerState.DISCONNECTED;
    38  
    39      /** A history of transactions for debugging purposes. */
    40      protected RollingList<String> history = new RollingList<String>(10);
    41  
    42      /**
    43       * Transitions the status of this object to the specified state.
    44       *
    45       * @param newState The state to transition to
    46       */
    47      public synchronized void transition(final ServerState newState) {
                 /* 
    P/P           *  Method: void transition(ServerState)
                  * 
                  *  Preconditions:
                  *    newState != null
                  *    this.state != null
                  *    this.history != null
                  *    this.state.transitions != null
                  * 
                  *  Presumptions:
                  *    java.util.List:contains(...)@101 == 1
                  * 
                  *  Postconditions:
                  *    this.state == newState
                  *    this.state != null
                  */
    48          addHistoryEntry(state, newState);
    49  
    50          if (state.canTransitionTo(newState)) {
    51              state = newState;
    52  
    53              synchronized (this) {
    54                  notifyAll();
    55              }
    56          } else {
    57              throw new IllegalArgumentException("Illegal server state "
    58                      + "transition\n\n" + getTransitionHistory());
    59          }
    60      }
    61  
    62      /**
    63       * Retrieves the current state of this status object.
    64       *
    65       * @return This object's current state
    66       */
    67      public synchronized ServerState getState() {
                 /* 
    P/P           *  Method: ServerState getState()
                  * 
                  *  Preconditions:
                  *    init'ed(this.state)
                  * 
                  *  Postconditions:
                  *    return_value == this.state
                  *    init'ed(return_value)
                  */
    68          return state;
    69      }
    70  
    71      /**
    72       * Adds a history entry to this status object. The history entry contains
    73       * the name of the states being transitioned between, the details of the
    74       * method (and class and line) which initiated the transition, and the
    75       * name of the thread in which the transition is occuring.
    76       *
    77       * @param fromState The state which is being transitioned from
    78       * @param toState The state which is being transitioned to
    79       */
    80      protected void addHistoryEntry(final ServerState fromState, final ServerState toState) {
                 /* 
    P/P           *  Method: void addHistoryEntry(ServerState, ServerState)
                  * 
                  *  Preconditions:
                  *    fromState != null
                  *    this.history != null
                  *    toState != null
                  * 
                  *  Presumptions:
                  *    java.lang.Thread:currentThread(...)@86 != null
                  *    java.lang.Thread:currentThread(...)@88 != null
                  *    java.lang.Thread:getStackTrace(...).length@86 >= 4
                  *    java.lang.Thread:getStackTrace(...)@86 != null
                  *    java.lang.Thread:getStackTrace(...)[3]@86 != null
                  */
    81          final StringBuilder builder = new StringBuilder();
    82          builder.append(fromState.name());
    83          builder.append("->");
    84          builder.append(toState.name());
    85          builder.append(' ');
    86          builder.append(Thread.currentThread().getStackTrace()[3].toString());
    87          builder.append(" [");
    88          builder.append(Thread.currentThread().getName());
    89          builder.append(']');
    90  
    91          history.add(builder.toString());
    92      }
    93  
    94      /**
    95       * Retrieves the transition history of this status object as a string.
    96       *
    97       * @see #addHistoryEntry(com.dmdirc.ServerState, com.dmdirc.ServerState)
    98       * @return A line feed ('\n') delimited string containing one entry for
    99       * each of the entries in this status's transition history.
   100       */
   101      public String getTransitionHistory() {
                 /* 
    P/P           *  Method: String getTransitionHistory()
                  * 
                  *  Preconditions:
                  *    this.history != null
                  * 
                  *  Presumptions:
                  *    com.dmdirc.util.RollingList:getList(...)@104 != null
                  * 
                  *  Postconditions:
                  *    java.lang.StringBuilder:toString(...)._tainted == 0
                  *    return_value == &amp;java.lang.StringBuilder:toString(...)
                  * 
                  *  Test Vectors:
                  *    java.lang.StringBuilder:length(...)@105: {-231..0}, {1..232-1}
                  *    java.util.Iterator:hasNext(...)@104: {0}, {1}
                  */
   102          final StringBuilder builder = new StringBuilder();
   103  
   104          for (String line : history.getList()) {
   105              if (builder.length() > 0) {
   106                  builder.append('\n');
   107              }
   108  
   109              builder.append(line);
   110          }
   111  
   112          return builder.toString();
   113      }
   114  
   115  }