1. Project Clover database Sat Feb 2 2019 06:45:20 CET
  2. Package org.xwiki.rendering.block

File Block.java

 

Code metrics

0
0
0
2
304
50
0
-
-
0
-

Classes

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