Item


1   package hudson.model;
2   
3   import java.io.IOException  ;
4   import java.util.Collection  ;
5   
6   /**
7    * Basic configuration unit in Hudson.
8    *
9    * <p>
10   * Every {@link Item} is hosted in an {@link ItemGroup} called "parent",
11   * and some {@link Item}s are {@link ItemGroup}s. This form a tree
12   * structure, which is rooted at {@link Hudson}.
13   *
14   * <p>
15   * Unlike file systems, where a file can be moved from one directory
16   * to another, {@link Item} inherently belongs to a single {@link ItemGroup}
17   * and that relationship will not change.
18   * Think of
19   * <a HREF="http://images.google.com/images?q=Windows%20device%20manager">Windows device manager</a>
20   * &mdash; an HDD always show up under 'Disk drives' and it can never be moved to another parent.
21   *
22   * Similarly, {@link ItemGroup} is not a generic container. Each subclass
23   * of {@link ItemGroup} can usually only host a certain limited kinds of
24   * {@link Item}s.
25   *
26   * <p>
27   * {@link Item}s have unique {@link #getName() name}s that distinguish themselves
28   * among their siblings uniquely. The names can be combined by '/' to form an
29   * item full name, which uniquely identifies an {@link Item} inside the whole {@link Hudson}.
30   *
31   * @author Kohsuke Kawaguchi
32   * @see Items
33   */
34  public interface Item extends PersistenceRoot {
35      /**
36       * Gets the parent that contains this item.
37       */
38      ItemGroup<? extends Item> getParent();
39  
40      /**
41       * Gets all the jobs that this {@link Item} contains as descendants.
42       */
43      abstract Collection  <? extends Job> getAllJobs();
44  
45      /**
46       * Gets the name of the item.
47       *
48       * <p>
49       * The name must be unique among other {@link Item}s that belong
50       * to the same parent.
51       *
52       * <p>
53       * This name is also used for directory name, so it cannot contain
54       * any character that's not allowed on the file system. 
55       */
56      String   getName();
57  
58      /**
59       * Gets the full name of this item, like "abc/def/ghi".
60       *
61       * <p>
62       * Full name consists of {@link #getName() name}s of {@link Item}s
63       * that lead from the root {@link Hudson} to this {@link Item},
64       * separated by '/'. This is the unique name that identifies this
65       * {@link Item} inside the whole {@link Hudson}.
66       *
67       * @see Hudson#getItemByFullName(String,Class)
68       */
69      String   getFullName();
70  
71      /**
72       * Returns the URL of this item relative to the context root of the application.
73       *
74       * @see AbstractItem#getUrl() for how to implement this.
75       */
76      String   getUrl();
77  
78      /**
79       * Returns the URL of this item relative to the parent {@link ItemGroup}.
80       * @see AbstractItem#getShortUrl() for how to implement this.
81       */
82      String   getShortUrl();
83  
84      /**
85       * Called right after when a {@link Item} is loaded from disk.
86       * This is an opporunity to do a post load processing.
87       *
88       * @param name
89       *      Name of the directory (not a path --- just the name portion) from
90       *      which the configuration was loaded. This usually becomes the
91       *      {@link #getName() name} of this item.
92       */
93      void onLoad(ItemGroup<? extends Item> parent, String   name) throws IOException  ;
94  
95      /**
96       * When a {@link Item} is copied from existing one,
97       * the files are first copied on the file system,
98       * then it will be loaded, then this method will be invoked
99       * to perform any implementation-specific work.
100      */
101     void onCopiedFrom(Item src);
102 
103     /**
104      * Save the settings to a file.
105      *
106      * Use {@link Items#getConfigFile(Item)}
107      * or {@link AbstractItem#getConfigFile()} to obtain the file
108      * to save the data.
109      */
110     public void save() throws IOException  ;
111 }
112
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags