1 /* 2 * Copyright (C) 2009 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package com.android.vcard; 17 18 import com.android.vcard.exception.VCardException; 19 20 import java.io.IOException; 21 import java.io.InputStream; 22 23 public abstract class VCardParser { 24 25 /** 26 * Registers one {@link VCardInterpreter} instance, which receives events along with 27 * vCard parsing. 28 * 29 * @param interpreter 30 */ addInterpreter(VCardInterpreter interpreter)31 public abstract void addInterpreter(VCardInterpreter interpreter); 32 33 /** 34 * <p>Parses a whole InputStream as a vCard file and lets registered {@link VCardInterpreter} 35 * instances handle callbacks.</p> 36 * 37 * <p>This method reads a whole InputStream. If you just want to parse one vCard entry inside 38 * a vCard file with multiple entries, try {@link #parseOne(InputStream)}.</p> 39 * 40 * @param is The source to parse. 41 * @throws IOException, VCardException 42 */ parse(InputStream is)43 public abstract void parse(InputStream is) throws IOException, VCardException; 44 45 /** 46 * <p>Parses the first vCard entry in InputStream and lets registered {@link VCardInterpreter} 47 * instances handle callbacks.</p> 48 * 49 * <p>This method finishes itself when the first entry ended.</p> 50 * 51 * <p>Note that, registered {@link VCardInterpreter} may still see multiple 52 * {@link VCardInterpreter#onEntryStarted()} / {@link VCardInterpreter#onEntryEnded()} calls 53 * even with this method.</p> 54 * 55 * <p>This happens when the first entry contains nested vCards, which is allowed in vCard 2.1. 56 * See the following example.</p> 57 * 58 * <code> 59 * BEGIN:VCARD 60 * N:a 61 * BEGIN:VCARD 62 * N:b 63 * END:VCARD 64 * END:VCARD 65 * </code> 66 * 67 * <p>With this vCard, registered interpreters will grab two 68 * {@link VCardInterpreter#onEntryStarted()} and {@link VCardInterpreter#onEntryEnded()} 69 * calls. Callers should handle the situation by themselves.</p> 70 * 71 * @param is The source to parse. 72 * @throws IOException, VCardException 73 */ parseOne(InputStream is)74 public abstract void parseOne(InputStream is) throws IOException, VCardException; 75 76 /** 77 * @deprecated use {@link #addInterpreter(VCardInterpreter)} and 78 * {@link #parse(InputStream)} 79 */ 80 @Deprecated parse(InputStream is, VCardInterpreter interpreter)81 public void parse(InputStream is, VCardInterpreter interpreter) 82 throws IOException, VCardException { 83 addInterpreter(interpreter); 84 parse(is); 85 } 86 87 /** 88 * <p> 89 * Cancel parsing vCard. Useful when you want to stop the parse in the other threads. 90 * </p> 91 * <p> 92 * Actual cancel is done after parsing the current vcard. 93 * </p> 94 */ cancel()95 public abstract void cancel(); 96 } 97