001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2017 MicroBean.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
014 * implied.  See the License for the specific language governing
015 * permissions and limitations under the License.
016 */
017package org.microbean.helm.chart;
018
019import java.io.Closeable;
020import java.io.IOException;
021
022import hapi.chart.ChartOuterClass.Chart; // for javadoc only
023import hapi.chart.ChartOuterClass.Chart.Builder;
024
025/**
026 * An abstract class whose implementations are capable of reading in
027 * the raw materials for a {@linkplain Chart Helm chart} from some
028 * kind of <em>source</em> and creating new {@link Chart} instances
029 * from such raw materials.
030 *
031 * <p><strong>Implementations should pay close attention to any
032 * potential resource leaks and control them in their implementation
033 * of the {@link Closeable#close()} method.</strong></p>
034 *
035 * @param <T> the type of source from which {@link Chart}s may be
036 * loaded
037 *
038 * @author <a href="https://about.me/lairdnelson"
039 * target="_parent">Laird Nelson</a>
040 *
041 * @see #load(Object)
042 *
043 * @see #load(hapi.chart.ChartOuterClass.Chart.Builder, Object)
044 *
045 * @see Chart
046 */
047public abstract class AbstractChartLoader<T> implements Closeable {
048
049
050  /*
051   * Constructors.
052   */
053
054
055  /**
056   * Creates a new {@link AbstractChartLoader}.
057   */
058  protected AbstractChartLoader() {
059    super();
060  }
061
062
063  /*
064   * Instance methods.
065   */
066  
067  
068  /**
069   * Creates a new "top-level" {@link Builder} from the supplied
070   * {@code source} and returns it.
071   *
072   * <p>Implementations of this method must not return {@code null}.</p>
073   *
074   * @param source the source from which a new {@link Builder} should be
075   * created; must not be {@code null}
076   *
077   * @return a new {@link Builder}; never {@code null}
078   *
079   * @exception NullPointerException if {@code source} is {@code null}
080   *
081   * @exception IOException if reading the supplied {@code source}
082   * could not complete normally
083   *
084   * @see #load(ChartOuterClass.Chart.Builder, Object)
085   */
086  public final Builder load(final T source) throws IOException {
087    return this.load(null, source);
088  }
089  
090  /**
091   * Creates a new {@link Builder} from the supplied {@code source}
092   * and returns it.
093   *
094   * <p>Implementations of this method must not return {@code null}
095   * and must not return {@code parent}.</p>
096   *
097   * @param parent the {@link Builder} that will serve as the parent
098   * of the {@link Builder} that will be returned; may be (and often
099   * is) {@code null}, indicating that the {@link Builder} being
100   * returned does not represent a subchart; must not be what is
101   * returned
102   *
103   * @param source the source from which a new {@link Builder} should
104   * be created; must not be {@code null}
105   *
106   * @return a new {@link Builder}; never {@code null}; never {@code
107   * parent}
108   *
109   * @exception NullPointerException if {@code source} is {@code null}
110   *
111   * @exception IOException if reading the supplied {@code source}
112   * could not complete normally
113   */
114  public abstract Builder load(final Builder parent, final T source) throws IOException;
115
116}