org.argeo.slc.repo/src/org/eclipse/aether/RequestTrace.java

   1 /*******************************************************************************
   2  * Copyright (c) 2010, 2011 Sonatype, Inc.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Eclipse Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/epl-v10.html
   7  *
   8  * Contributors:
   9  *    Sonatype, Inc. - initial API and implementation
  10  *******************************************************************************/
  11 package org.eclipse.aether;
  12
  13 /**
  14  * A trace of nested requests that are performed by the repository system. This trace information can be used to
  15  * correlate repository events with higher level operations in the application code that eventually caused the events. A
  16  * single trace can carry an arbitrary object as data which is meant to describe a request/operation that is currently
  17  * executed. For call hierarchies within the repository system itself, this data will usually be the {@code *Request}
  18  * object that is currently processed. When invoking methods on the repository system, client code may provide a request
  19  * trace that has been prepopulated with whatever data is useful for the application to indicate its state for later
  20  * evaluation when processing the repository events.
  21  *
  22  * @see RepositoryEvent#getTrace()
  23  */
  24 public class RequestTrace
  25 {
  26
  27     private final RequestTrace parent;
  28
  29     private final Object data;
  30
  31     /**
  32      * Creates a child of the specified request trace. This method is basically a convenience that will invoke
  33      * {@link RequestTrace#newChild(Object) parent.newChild()} when the specified parent trace is not {@code null} or
  34      * otherwise instantiante a new root trace.
  35      *
  36      * @param parent The parent request trace, may be {@code null}.
  37      * @param data The data to associate with the child trace, may be {@code null}.
  38      * @return The child trace, never {@code null}.
  39      */
  40     public static RequestTrace newChild( RequestTrace parent, Object data )
  41     {
  42         if ( parent == null )
  43         {
  44             return new RequestTrace( data );
  45         }
  46         return parent.newChild( data );
  47     }
  48
  49     /**
  50      * Creates a new root trace with the specified data.
  51      *
  52      * @param data The data to associate with the trace, may be {@code null}.
  53      */
  54     public RequestTrace( Object data )
  55     {
  56         this( null, data );
  57     }
  58
  59     /**
  60      * Creates a new trace with the specified data and parent
  61      *
  62      * @param parent The parent trace, may be {@code null} for a root trace.
  63      * @param data The data to associate with the trace, may be {@code null}.
  64      */
  65     protected RequestTrace( RequestTrace parent, Object data )
  66     {
  67         this.parent = parent;
  68         this.data = data;
  69     }
  70
  71     /**
  72      * Gets the data associated with this trace.
  73      *
  74      * @return The data associated with this trace or {@code null} if none.
  75      */
  76     public final Object getData()
  77     {
  78         return data;
  79     }
  80
  81     /**
  82      * Gets the parent of this trace.
  83      *
  84      * @return The parent of this trace or {@code null} if this is the root of the trace stack.
  85      */
  86     public final RequestTrace getParent()
  87     {
  88         return parent;
  89     }
  90
  91     /**
  92      * Creates a new child of this trace.
  93      *
  94      * @param data The data to associate with the child, may be {@code null}.
  95      * @return The child trace, never {@code null}.
  96      */
  97     public RequestTrace newChild( Object data )
  98     {
  99         return new RequestTrace( this, data );
 100     }
 101
 102     @Override
 103     public String toString()
 104     {
 105         return String.valueOf( getData() );
 106     }
 107
 108 }