org.apache.stanbol.enhancer.servicesapi.ContentSource Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.apache.stanbol.enhancer.servicesapi Show documentation
The Enhancer (formally FISE) Services API
The newest version!
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements.  See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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 org.apache.stanbol.enhancer.servicesapi;

import java.io.IOException;
import java.io.InputStream;
import java.util.List;
import java.util.Map;

/**
 * The content source representing the data and optionally the media type
 * and file name. This interface is only used to parse the content
 * when creating a {@link ContentItem}. To obtain the content of a
 * ContentItem the {@link Blob} interface is used
 * NOTE that {@link #getStream()} can typically only be called a single time.
 * Multiple calls will throw an {@link IllegalArgumentException}.
 * @see Blob
 */
public interface ContentSource {
    /**
     * Getter for the data as stream. This method might only work a single time so
     * multiple calls might result in {@link IllegalStateException}s.

     * {@link ContentItem}/{@link Blob} implementations that keep the
     * content in memory should preferable use {@link #getData()} to
     * obtain the content from the source.
     * @return the data.
     * @throws IllegalStateException if the stream is already consumed and
     * can not be re-created.
     * @see #getStream()
     */
    InputStream getStream();
    /**
     * Getter for the data as byte array. 

     * NOTE that his method will load
     * the content in-memory. However using this method instead of
     * {@link #getStream()} might preserve holding multiple in-memory version
     * of the same content in cases where both the {@link ContentSource}
     * and the {@link ContentItem} are internally using an byte array to
     * hold the content.  
     * As a rule of thumb this method should only be
     * used by in-memory {@link ContentItem}/{@link Blob} implementations.
     * @return the content as byte array.
     * @throws IOException On any error while reading the data from the source.
     * @throws IllegalStateException If the {@link #getStream()} was already
     * consumed when calling this method.
     * @see #getStream()
     */
    byte[] getData() throws IOException;
    /**
     * An valid media type as defined by 
     * RFC2046.
     * "application/octet-stream" if unknown
     * @return The media type or null if unknown
     */
    String getMediaType();
    /**
     * The original file name.
     * @return the name of the file or null if not known
     */
    String getFileName();
    /**
     * Getter for additional header information about the ContentSource. The
     * returned Map MUST NOT be null and MAY be read-only.
     * @return additional header information.
     */
    Map> getHeaders();
}