1. Project Clover database Tue Dec 20 2016 21:24:09 CET
  2. Package org.xwiki.rendering.block

File Block.java

 

Code metrics

0
0
0
2
295
47
0
-
-
0
-

Classes

Class Line # Actions
Block 36 0 - 0 0
-1.0 -
Block.Axes 44 0 - 0 0
-1.0 -
 

Contributing tests

No tests hitting this source file were found.

Source view

1    /*
2    * See the NOTICE file distributed with this work for additional
3    * information regarding copyright ownership.
4    *
5    * This is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU Lesser General Public License as
7    * published by the Free Software Foundation; either version 2.1 of
8    * the License, or (at your option) any later version.
9    *
10    * This software is distributed in the hope that it will be useful,
11    * but WITHOUT ANY WARRANTY; without even the implied warranty of
12    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13    * Lesser General Public License for more details.
14    *
15    * You should have received a copy of the GNU Lesser General Public
16    * License along with this software; if not, write to the Free
17    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
18    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
19    */
20    package org.xwiki.rendering.block;
21   
22    import java.util.List;
23    import java.util.Map;
24   
25    import org.xwiki.rendering.block.match.BlockMatcher;
26    import org.xwiki.rendering.listener.Listener;
27   
28    /**
29    * Represents an element of a XWiki Document's content. For example there are Blocks for Paragraphs, Bold parts,
30    * Sections, Links, etc. A block has a parent and can have children too for Blocks which are wrapper around other blocks
31    * (e.g. Paragraph blocks, List blocks, Bold blocks).
32    *
33    * @version $Id: e88f60bd9fc01625171c7708c99c15bd066f1c7c $
34    * @since 1.5M2
35    */
 
36    public interface Block extends Cloneable
37    {
38    /**
39    * Search axes used in searching methods. Mostly taken from XPATH axes.
40    *
41    * @version $Id: e88f60bd9fc01625171c7708c99c15bd066f1c7c $
42    * @since 3.0M3
43    */
 
44    enum Axes
45    {
46   
47    /** Just the context block itself. */
48    SELF,
49   
50    /** The parent of the context block, if there is one. */
51    PARENT,
52   
53    /**
54    * The ancestors of the context block; the ancestors of the context block consist of the parent of context block
55    * and the parent's parent and so on; thus, the ancestor axis will always include the root block, unless the
56    * context block is the root block.
57    */
58    ANCESTOR,
59   
60    /**
61    * The context block and the ancestors of the context block; thus, the ancestor axis will always include the
62    * root block.
63    */
64    ANCESTOR_OR_SELF,
65   
66    /** The children of the context block. */
67    CHILD,
68   
69    /** The descendants of the context block; a descendant is a child or a child of a child and so on. */
70    DESCENDANT,
71   
72    /** The context block and the descendants of the context block. */
73    DESCENDANT_OR_SELF,
74   
75    /**
76    * All blocks in the same document as the context block that are after the context block in document order,
77    * excluding any descendants.
78    */
79    FOLLOWING,
80   
81    /** All the following siblings of the context block. */
82    FOLLOWING_SIBLING,
83   
84    /**
85    * All blocks in the same document as the context block that are before the context block in document order,
86    * excluding any ancestors.
87    */
88    PRECEDING,
89   
90    /** All the preceding siblings of the context block. */
91    PRECEDING_SIBLING
92    }
93   
94    /**
95    * Let the block send {@link Listener} events corresponding to its content. For example a Paragraph block will send
96    * the {@link org.xwiki.rendering.listener.Listener#beginParagraph} and
97    * {@link org.xwiki.rendering.listener.Listener#endParagraph} events when this method is called.
98    *
99    * @param listener the listener to which to send the events to.
100    */
101    void traverse(Listener listener);
102   
103    /**
104    * Helper method to add a single child block to the end of the children list of the current block. For adding
105    * several blocks at once use {@link #addChildren(java.util.List)}.
106    *
107    * @param blockToAdd the child block to add
108    */
109    void addChild(Block blockToAdd);
110   
111    /**
112    * Adds several children blocks to the end of the children list of the current block. For example a bold sentence is
113    * made up of a Bold block to which the different words making up the text have been added to.
114    *
115    * @param blocksToAdd the children blocks to add
116    */
117    void addChildren(List<? extends Block> blocksToAdd);
118   
119    /**
120    * Replace current children by the provided list of {@link Block}s.
121    *
122    * @param children the new children
123    */
124    void setChildren(List<? extends Block> children);
125   
126    /**
127    * Helper method to add a single child block to the current block before the provided existing child block. For
128    * adding several blocks at once use {@link #addChildren(java.util.List)}.
129    *
130    * @param blockToInsert the child block to add
131    * @param nextBlock the child block that will be just after the added block
132    * @since 1.6M1
133    */
134    void insertChildBefore(Block blockToInsert, Block nextBlock);
135   
136    /**
137    * Helper method to add a single child block to the current block after the provided existing child block. For
138    * adding several blocks at once use {@link #addChildren(java.util.List)}.
139    *
140    * @param blockToInsert the child block to add
141    * @param previousBlock the child block that will be just before the added block
142    * @since 1.6M1
143    */
144    void insertChildAfter(Block blockToInsert, Block previousBlock);
145   
146    /**
147    * Replaces an existing children block with the passed new block. Also sets the new block's parent to be the current
148    * block.
149    *
150    * @param newBlock the new block to replace the old block with
151    * @param oldBlock the block to replace with the new block
152    */
153    void replaceChild(Block newBlock, Block oldBlock);
154   
155    /**
156    * Replaces an existing children block with the passed new blocks. Also sets the new block's parents to be the
157    * current block.
158    *
159    * @param newBlocks the new blocks to replace the old block with
160    * @param oldBlock the block to replace with the new blocks
161    */
162    void replaceChild(List<Block> newBlocks, Block oldBlock);
163   
164    /**
165    * Get the parent block. All blocks have a parent and the top level parent is the {@link XDOM} object.
166    *
167    * @return the parent block
168    */
169    Block getParent();
170   
171    /**
172    * Sets the parent block.
173    *
174    * @param parentBlock the parent block
175    */
176    void setParent(Block parentBlock);
177   
178    /**
179    * Gets all children blocks.
180    *
181    * @return the children blocks
182    * @see #addChildren(java.util.List)
183    */
184    List<Block> getChildren();
185   
186    /**
187    * Gets the top level Block. If the current block is the top level Block, it return itself.
188    *
189    * @return the top level Block
190    */
191    Block getRoot();
192   
193    /**
194    * Removes a Block.
195    *
196    * @param childBlockToRemove the child block to remove
197    * @since 2.6RC1
198    */
199    void removeBlock(Block childBlockToRemove);
200   
201    /**
202    * @return the next sibling block or null if there's no next sibling
203    * @since 2.6RC1
204    */
205    Block getNextSibling();
206   
207    /**
208    * @param nextSiblingBlock see {@link #getNextSibling()}
209    * @since 2.6RC1
210    */
211    void setNextSiblingBlock(Block nextSiblingBlock);
212   
213    /**
214    * @return the previous sibling block or null if there's no previous sibling
215    * @since 2.6RC1
216    */
217    Block getPreviousSibling();
218   
219    /**
220    * @param previousSiblingBlock see {@link #getPreviousSibling()} ()}
221    * @since 2.6RC1
222    */
223    void setPreviousSiblingBlock(Block previousSiblingBlock);
224   
225    /**
226    * Return a copy of the block with filtered children.
227    *
228    * @param blockFilter the Block filter.
229    * @return the filtered Block.
230    * @since 1.8RC2
231    */
232    Block clone(BlockFilter blockFilter);
233   
234    /**
235    * @return the cloned Block
236    * @see Object#clone()
237    */
238    Block clone();
239   
240    /**
241    * @return all parameters
242    * @since 3.0M1
243    */
244    Map<String, String> getParameters();
245   
246    /**
247    * A Parameter is a generic key/value which can be used to add metadata to a block. What is done with the metadata
248    * depends on the Renderer's implementations. For example the XHTML Renderer adds them as Element attributes.
249    *
250    * @param name the name of the parameter to return
251    * @return the parameter or null if the parameter doesn't exist
252    * @since 3.0M1
253    */
254    String getParameter(String name);
255   
256    /**
257    * Set a parameter on the current block. See {@link #getParameter(String)} for more details.
258    *
259    * @param name the parameter's name
260    * @param value the parameter's value
261    * @since 3.0M1
262    */
263    void setParameter(String name, String value);
264   
265    /**
266    * Set several parameters at once.
267    *
268    * @param parameters the parameters to set
269    * @see #getParameter(String)
270    * @since 3.0M1
271    */
272    void setParameters(Map<String, String> parameters);
273   
274    /**
275    * Get all blocks following provided {@link BlockMatcher} and {@link Axes}.
276    *
277    * @param <T> the class of the Blocks to return
278    * @param matcher filter the blocks to return
279    * @param axes indicate the search axes
280    * @return the matched {@link Block}s, empty list of none was found
281    * @since 3.0M3
282    */
283    <T extends Block> List<T> getBlocks(BlockMatcher matcher, Axes axes);
284   
285    /**
286    * Get the first matched block in the provided {@link Axes}.
287    *
288    * @param <T> the class of the Block to return
289    * @param matcher indicate which block to stop to
290    * @param axes indicate the search axes
291    * @return the matched {@link Block}, null if none was found
292    * @since 3.0M3
293    */
294    <T extends Block> T getFirstBlock(BlockMatcher matcher, Axes axes);
295    }