View Javadoc
1   package org.codehaus.plexus.javadoc;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.util.Map;
23  
24  import com.sun.tools.doclets.Taglet;
25  
26  /**
27   * Tagging a field with <tt>@plexus.requirement</tt> will tell plexus to inject the required component or
28   * list of components before the component itself is started. Fields can be of the type of the Interface
29   * defining the component you wish to be injected or of type <tt>java.util.List</tt> or <tt>java.util.Map</tt>.
30   * <br/>
31   * Fields of type <tt>java.lang.List</tt> will have a list of components injected whereas a field of
32   * type <tt>java.lang.Map</tt> will have a mapping in the form of <tt>role-hint -&gt; component</tt>.
33   * The <tt>role</tt> parameter is required if using a <tt>List</tt> or <tt>Map</tt> whereas a role-hint is
34   * not allowed.
35   * <table class="bodyTable">
36   *   <tbody>
37   *     <tr class="a">
38   *       <td align="left"><b>Parameter</b></td>
39   *       <td align="left"><b>Required</b></td>
40   *       <td align="left"><b>Description</b></td>
41   *     </tr>
42   *     <tr class="b">
43   *       <td align="left">role</td>
44   *       <td align="left">No. Yes if the field is a <tt>List</tt> or a <tt>Map</tt></td>
45   *       <td align="left">The role parameter is used to tell plexus what Component role you are interested in.
46   *       For singleton fields their type is used as a default.</td>
47   *     </tr>
48   *     <tr class="a">
49   *       <td align="left">role-hint</td>
50   *       <td align="left">No. Not allowed if the field is a <tt>List</tt> or a <tt>Map</tt></td>
51   *       <td align="left">Links to the role-hint defined by a component when looking up a component.
52   *       Not allowed with <tt>List</tt> or <tt>Map</tt> fields, as they return all <tt>role-hint</tt>s.</td>
53   *     </tr>
54   *   </tbody>
55   * </table>
56   *
57   * @see <a href="http://plexus.codehaus.org/guides/developer-guide/appendices/javadoc-tags-reference.html">
58   * http://plexus.codehaus.org/guides/developer-guide/appendices/javadoc-tags-reference.html</a>;
59   *
60   * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
61   * @version $Id$
62   */
63  public class PlexusRequirementTaglet
64      extends AbstractPlexusTaglet
65  {
66      private static final String NAME = "plexus.requirement";
67  
68      private static final String HEADER = "Plexus requirement";
69  
70      /** {@inheritDoc} */
71      public String getHeader()
72      {
73          return HEADER;
74      }
75  
76      /** {@inheritDoc} */
77      public String getName()
78      {
79          return NAME;
80      }
81  
82      /** {@inheritDoc} */
83      public boolean inConstructor()
84      {
85          return false;
86      }
87  
88      /** {@inheritDoc} */
89      public boolean inField()
90      {
91          return true;
92      }
93  
94      /** {@inheritDoc} */
95      public boolean inMethod()
96      {
97          return false;
98      }
99  
100     /** {@inheritDoc} */
101     public boolean inOverview()
102     {
103         return false;
104     }
105 
106     /** {@inheritDoc} */
107     public boolean inPackage()
108     {
109         return false;
110     }
111 
112     /** {@inheritDoc} */
113     public boolean inType()
114     {
115         return false;
116     }
117 
118     /** {@inheritDoc} */
119     public boolean isInlineTag()
120     {
121         return false;
122     }
123 
124     /**
125      * Register this Taglet.
126      *
127      * @param tagletMap the map to register this tag to.
128      */
129     public static void register( Map tagletMap )
130     {
131         PlexusRequirementTaglet tag = new PlexusRequirementTaglet();
132         Taglet t = (Taglet) tagletMap.get( tag.getName() );
133         if ( t != null )
134         {
135             tagletMap.remove( tag.getName() );
136         }
137         tagletMap.put( tag.getName(), tag );
138     }
139 }