14199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa/* 24199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * Copyright (C) 2009 The Android Open Source Project 34199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * 44199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * Licensed under the Apache License, Version 2.0 (the "License"); 54199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * you may not use this file except in compliance with the License. 64199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * You may obtain a copy of the License at 74199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * 84199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * http://www.apache.org/licenses/LICENSE-2.0 94199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * 104199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * Unless required by applicable law or agreed to in writing, software 114199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * distributed under the License is distributed on an "AS IS" BASIS, 124199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 134199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * See the License for the specific language governing permissions and 144199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * limitations under the License. 154199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa */ 164199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawapackage com.android.vcard; 174199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa 184199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawaimport com.android.vcard.exception.VCardException; 194199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa 204199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawaimport java.io.IOException; 214199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawaimport java.io.InputStream; 224199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa 231de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawapublic abstract class VCardParser { 2456650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa 254199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa /** 2656650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * Registers one {@link VCardInterpreter} instance, which receives events along with 2756650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * vCard parsing. 2856650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * 2956650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * @param interpreter 3056650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa */ 3156650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa public abstract void addInterpreter(VCardInterpreter interpreter); 3256650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa 3356650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa /** 3456650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * <p>Parses a whole InputStream as a vCard file and lets registered {@link VCardInterpreter} 3556650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * instances handle callbacks.</p> 3656650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * 3756650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * <p>This method reads a whole InputStream. If you just want to parse one vCard entry inside 3856650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * a vCard file with multiple entries, try {@link #parseOne(InputStream)}.</p> 394199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * 404199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * @param is The source to parse. 414199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * @throws IOException, VCardException 4256650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa */ 4356650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa public abstract void parse(InputStream is) throws IOException, VCardException; 4456650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa 4556650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa /** 4656650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * <p>Parses the first vCard entry in InputStream and lets registered {@link VCardInterpreter} 4756650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * instances handle callbacks.</p> 4856650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * 4956650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * <p>This method finishes itself when the first entry ended.</p> 5056650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * 5156650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * <p>Note that, registered {@link VCardInterpreter} may still see multiple 5256650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * {@link VCardInterpreter#onEntryStarted()} / {@link VCardInterpreter#onEntryEnded()} calls 5356650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * even with this method.</p> 5456650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * 5556650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * <p>This happens when the first entry contains nested vCards, which is allowed in vCard 2.1. 5656650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * See the following example.</p> 5756650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * 5856650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * <code> 5956650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * BEGIN:VCARD 6056650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * N:a 6156650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * BEGIN:VCARD 6256650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * N:b 6356650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * END:VCARD 6456650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * END:VCARD 6556650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * </code> 6656650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * 6756650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * <p>With this vCard, registered interpreters will grab two 6856650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * {@link VCardInterpreter#onEntryStarted()} and {@link VCardInterpreter#onEntryEnded()} 6956650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * calls. Callers should handle the situation by themselves.</p> 7056650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * 7156650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * @param is The source to parse. 7256650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa * @throws IOException, VCardException 7356650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa */ 7456650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa public abstract void parseOne(InputStream is) throws IOException, VCardException; 7556650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa 7656650608f09fc75f260c03e00456ef3d1e60c929Daisuke Miyakawa /** 771de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawa * @deprecated use {@link #addInterpreter(VCardInterpreter)} and 781de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawa * {@link #parse(InputStream)} 794199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa */ 801de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawa @Deprecated 811de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawa public void parse(InputStream is, VCardInterpreter interpreter) 821de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawa throws IOException, VCardException { 831de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawa addInterpreter(interpreter); 841de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawa parse(is); 851de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawa } 861de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawa 874199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa /** 884199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * <p> 894199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * Cancel parsing vCard. Useful when you want to stop the parse in the other threads. 904199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * </p> 914199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * <p> 924199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * Actual cancel is done after parsing the current vcard. 934199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa * </p> 944199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa */ 951de396f6df89363169d3a2e61a61fa98d12c1ef8Daisuke Miyakawa public abstract void cancel(); 964199c54c527330ac01699b176e7bca186a3aa3a4Daisuke Miyakawa} 97