View Javadoc

1   package org.apache.maven.changelog;
2   
3   /* ====================================================================
4    *   Licensed to the Apache Software Foundation (ASF) under one or more
5    *   contributor license agreements.  See the NOTICE file distributed with
6    *   this work for additional information regarding copyright ownership.
7    *   The ASF licenses this file to You under the Apache License, Version 2.0
8    *   (the "License"); you may not use this file except in compliance with
9    *   the License.  You may obtain a copy of the License at
10   *
11   *       http://www.apache.org/licenses/LICENSE-2.0
12   *
13   *   Unless required by applicable law or agreed to in writing, software
14   *   distributed under the License is distributed on an "AS IS" BASIS,
15   *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   *   See the License for the specific language governing permissions and
17   *   limitations under the License.
18   * ====================================================================
19   */
20  
21  import java.io.IOException;
22  
23  import java.util.Collection;
24  
25  /**
26   * Instances of <code>ChangeLogGenerator</code> are intended to provide an
27   * {@link java.io.InputStream} for a {@link ChangeLogParser} to parse into
28   * individual {@link ChangeLogEntry} objects.
29   *
30   * @author Glenn McAllister
31   * @author dion
32   * @version $Id: ChangeLogGenerator.java 532339 2007-04-25 12:28:56Z ltheussl $
33   */
34  public interface ChangeLogGenerator
35  {
36      /**
37       * Initialize the ChangeLogGenerator instance with in the controlling
38       * {@link ChangeLog} instance.  Any configuration required for the generator
39       * should be obtained from the <code>changeLog</code>.  This method is
40       * guaranteed to be called before {@link #getEntries}.
41       *
42       * @param changeLog the controlling ChangeLog instance
43       */
44      void init( ChangeLog changeLog );
45  
46      /**
47       * Return a Collection of ChangeLogEntry objects.  This method should
48       * create an {@link java.io.InputStream} that contains the change log
49       * insformation which is then passed to the <code>parser</code> to create
50       * the individual {@link ChangeLogEntry} objects.
51       *
52       * <p>This method is guaranteed to be called after {@link #init} and before
53       * {@link #cleanup}.  This method must invoke <em>only</em> the {@link
54       * ChangeLogParser#parse} method.</p>
55       *
56       * @param parser the parser that will create the individual ChangeLogEntry
57       * objects.
58       * @return a Collection of ChangeLogEntry objects
59       * @throws IOException if there is an error while creating the
60       * ChangeLogEntry objects
61       */
62      Collection getEntries( ChangeLogParser parser )
63          throws IOException;
64  
65      /**
66       * Return a string indicating the start of the entries.
67       * This will usually be a date or a tag.
68       *
69       * @return  a string indicating the start of the entries.
70       */
71      String getLogStart();
72  
73      /**
74       * Return a string indicating the end of the entries.
75       * This will usually be a date or a tag.
76       *
77       * @return  a string indicating the end of the entries.
78       */
79      String getLogEnd();
80  
81      /**
82       * Provides the opportunity for the generator to do any required cleanup.
83       * This method is guaranteed to be called after the getEntries method even
84       * if an exception is thrown from getEntries.
85       */
86      void cleanup();
87  }