001 /**
002 * Copyright 2010-2012 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.codehaus.mojo.license.header.transformer;
017
018
019 import org.codehaus.mojo.license.header.FileHeader;
020
021 /**
022 * Contract to transform a file header to {@link FileHeader} in both way :
023 * <p/>
024 * <ul>
025 * <li>Obtain a object representation of a file header from a existing file
026 * (String to FileHeader).</li>
027 * <li>Obtain the file header to inject in a file from a FileHeader (to update
028 * or create a file header from the file header model).
029 * </ul>
030 * <p/>
031 * Moreover the contract offers two methods to box and unbox a String
032 * representation of a header content :
033 * <ul>
034 * <li>{@link #boxComment(String, boolean)}</li>
035 * <li>{@link #unboxComent(String)}</li>
036 * </ul>
037 *
038 * @author tchemit <chemit@codelutin.com>
039 * @since 1.0
040 */
041 public interface FileHeaderTransformer
042 {
043
044 /**
045 * Plexus component role
046 */
047 String ROLE_NAME = FileHeaderTransformer.class.getName();
048
049 /**
050 * default section delimiter
051 */
052 String DEFAULT_SECTION_DELIMITER = "%" + "%";
053
054 /**
055 * default process start tag
056 */
057 String DEFAULT_PROCESS_START_TAG = "#" + "%" + "L";
058
059 /**
060 * default process end tag
061 */
062 String DEFAULT_PROCESS_END_TAG = "#" + "L" + "%";
063
064 char LINE_SEPARATOR = '\n';
065
066 /**
067 * @return the name of the transformer
068 */
069 String getName();
070
071 /**
072 * @return the description of the transformer
073 */
074 String getDescription();
075
076 /**
077 * Get the default accepted extensions for this transformer.
078 *
079 * @return the default accepted extensions.
080 */
081 String[] getDefaultAcceptedExtensions();
082
083 /**
084 * Obtains the process tag which indicates the begin of the header content.
085 * <p/>
086 * By default, (says if you do not explicitly invoke the
087 * {@link #setProcessStartTag(String)} method), will use the
088 * {@link #DEFAULT_PROCESS_START_TAG}
089 *
090 * @return the starting header tag
091 */
092 String getProcessStartTag();
093
094 /**
095 * Obtain the process tag which indiciates the end of the header content.
096 * <p/>
097 * By default, (says if you do not explicitly invoke the
098 * {@link #setProcessEndTag(String)} method), will use the
099 * {@link #DEFAULT_PROCESS_END_TAG}.
100 *
101 * @return the ending header tag
102 */
103 String getProcessEndTag();
104
105 /**
106 * The pattern used to separate sections of the header.
107 * <p/>
108 * By default, (says if you do not explicitly invoke the
109 * {@link #setSectionDelimiter(String)} method), will use the
110 * {@link #DEFAULT_SECTION_DELIMITER}.
111 *
112 * @return the delimiter used to separate sections in the header.
113 */
114 String getSectionDelimiter();
115
116 /**
117 * @return the start tag of a comment
118 */
119 String getCommentStartTag();
120
121 /**
122 * @return the end tag of a comment
123 */
124 String getCommentEndTag();
125
126 /**
127 * @return the line prefix of every line insed the comment
128 */
129 String getCommentLinePrefix();
130
131 /**
132 * Adds the header.
133 *
134 * @param header header to add
135 * @param content content of original file
136 * @return the new full file content beginning with header
137 */
138 String addHeader( String header, String content );
139
140 /**
141 * Box the given {@code header} in a comment.
142 *
143 * @param header the header content WITHOUT any comment boxing
144 * @param withTags flag to add start and end comment tags.
145 * @return the header content WITH comment boxing
146 */
147 String boxComment( String header, boolean withTags );
148
149 /**
150 * Unbox the given boxed {@code boxedHeader} to obtain the header content.
151 *
152 * @param boxedHeader the boxed header
153 * @return the unboxed header.
154 */
155 String unboxComent( String boxedHeader );
156
157 /**
158 * Box the given {@code header} between process tags.
159 *
160 * @param header the header content WITHOUT any comment boxing
161 * @return the header content boxed between process tags
162 * @see #getProcessStartTag()
163 * @see #getProcessEndTag()
164 */
165 String boxProcessTag( String header );
166
167 /**
168 * Unbox the process tag on the given boxed {@code boxedHeader} to obtain
169 * the brute header content.
170 *
171 * @param boxedHeader the boxed header
172 * @return the brute header content.
173 * @see #getProcessStartTag()
174 * @see #getProcessEndTag()
175 */
176 String unboxProcessTag( String boxedHeader );
177
178 /**
179 * Build a {@link FileHeader} from an UNBOXED header content.
180 *
181 * @param header unboxed header content
182 * @return The model of the header content
183 */
184 FileHeader toFileHeader( String header );
185
186 /**
187 * Build a UNBOXED header content from the given {@code model}.
188 *
189 * @param model the model of the file header
190 * @return the UNBOXED header content
191 * @throws NullPointerException if model is null
192 */
193 String toString( FileHeader model )
194 throws NullPointerException;
195
196 /**
197 * Build a fully boxed header content from the given {@code model}.
198 *
199 * @param model the model of the file header
200 * @return the fully boxed header content
201 * @throws NullPointerException if model is null
202 */
203 String toHeaderContent( FileHeader model )
204 throws NullPointerException;
205
206 /**
207 * Tests if the description of the two models are equals.
208 *
209 * @param header1 the first header
210 * @param header2 the second header
211 * @return {@code true} if headers description are stricly the same
212 */
213 boolean isDescriptionEquals( FileHeader header1, FileHeader header2 );
214
215 /**
216 * Tests if the copyright of the two models are equals.
217 *
218 * @param header1 the first header
219 * @param header2 the second header
220 * @return {@code true} if headers copyright are stricly the same
221 */
222 boolean isCopyrightEquals( FileHeader header1, FileHeader header2 );
223
224 /**
225 * Tests if the license of the two models are equals.
226 *
227 * @param header1 the first header
228 * @param header2 the second header
229 * @return {@code true} if headers license are stricly the same (WITHOUT ANY space)
230 */
231 boolean isLicenseEquals( FileHeader header1, FileHeader header2 );
232
233 /**
234 * Changes the name of the transformer.
235 *
236 * @param name the new name of the transformer
237 */
238 void setName( String name );
239
240 /**
241 * Chages the description of the transformer.
242 *
243 * @param description the new description of the transformer
244 */
245 void setDescription( String description );
246
247 /**
248 * Sets the header section delimiter.
249 * <p/>
250 * By default, will use the {@link #DEFAULT_SECTION_DELIMITER}.
251 *
252 * @param headerSectionDelimiter the new delimiter
253 */
254 void setSectionDelimiter( String headerSectionDelimiter );
255
256 /**
257 * Changes the process start tag.
258 *
259 * @param tag the new start tag
260 */
261 void setProcessStartTag( String tag );
262
263 /**
264 * Changes the process end tag.
265 *
266 * @param tag the new endtag
267 */
268 void setProcessEndTag( String tag );
269
270 /**
271 * Changes the comment start tag.
272 *
273 * @param commentStartTag the new comment start tag
274 */
275 void setCommentStartTag( String commentStartTag );
276
277 /**
278 * Changes the comment end tag.
279 *
280 * @param commentEndTag the new comment end tag
281 */
282 void setCommentEndTag( String commentEndTag );
283
284 /**
285 * Changes the comment prefix line.
286 *
287 * @param commentLinePrefix the new comment prefix line
288 */
289 void setCommentLinePrefix( String commentLinePrefix );
290 }