content: /*
   * Copyright (C) 2009 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package com.android.vcard;
  
  import com.android.vcard.exception.VCardException;
  
  import java.io.IOException;
  import java.io.InputStream;
  
  public abstract class VCardParser {
  
      /**
       * Registers one {@link VCardInterpreter} instance, which receives events along with
       * vCard parsing.
       *
       * @param interpreter
       */
      public abstract void addInterpreter(VCardInterpreter interpreter);
  
      /**
       * <p>Parses a whole InputStream as a vCard file and lets registered {@link VCardInterpreter}
       * instances handle callbacks.</p>
       *
       * <p>This method reads a whole InputStream. If you just want to parse one vCard entry inside
       * a vCard file with multiple entries, try {@link #parseOne(InputStream)}.</p>
       *
       * @param is The source to parse.
       * @throws IOException, VCardException
       */
      public abstract void parse(InputStream is) throws IOException, VCardException;
  
      /**
       * <p>Parses the first vCard entry in InputStream and lets registered {@link VCardInterpreter}
       * instances handle callbacks.</p>
       *
       * <p>This method finishes itself when the first entry ended.</p>
       *
       * <p>Note that, registered {@link VCardInterpreter} may still see multiple
       * {@link VCardInterpreter#onEntryStarted()} / {@link VCardInterpreter#onEntryEnded()} calls
       * even with this method.</p>
       *
       * <p>This happens when the first entry contains nested vCards, which is allowed in vCard 2.1.
       * See the following example.</p>
       *
       * <code>
       * BEGIN:VCARD
       * N:a
       * BEGIN:VCARD
       * N:b
       * END:VCARD
       * END:VCARD
       * </code>
       *
       * <p>With this vCard, registered interpreters will grab two
       * {@link VCardInterpreter#onEntryStarted()} and {@link VCardInterpreter#onEntryEnded()}
       * calls. Callers should handle the situation by themselves.</p>
       *
       * @param is  The source to parse.
       * @throws IOException, VCardException
       */
      public abstract void parseOne(InputStream is) throws IOException, VCardException;
  
      /**
       * @deprecated use {@link #addInterpreter(VCardInterpreter)} and
       * {@link #parse(InputStream)}
       */
      @Deprecated
      public void parse(InputStream is, VCardInterpreter interpreter)
              throws IOException, VCardException {
          addInterpreter(interpreter);
          parse(is);
      }
  
      /**
       * <p>
       * Cancel parsing vCard. Useful when you want to stop the parse in the other threads.
       * </p>
       * <p>
       * Actual cancel is done after parsing the current vcard.
       * </p>
       */
      public abstract void cancel();
  }
  