org.osgl.storage.ISObject Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of osgl-storage Show documentation
A simple storage service supports plugin varieties of implementations including Amazon S3
There is a newer version: 1.11.1
/* 
 * Copyright (C) 2013 The Java Storage project
 * Gelin Luo 
 *
 * 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.osgl.storage;

import org.osgl.$;
import org.osgl.exception.UnexpectedIOException;

import java.io.File;
import java.io.InputStream;
import java.io.Serializable;
import java.nio.charset.Charset;
import java.util.Map;

/**
 * Represent an item stored in an IStorageService
 *
 * @author greenl
 */
public interface ISObject extends Serializable {

    /**
     * A standard attribute: content-type
     */
    public static final String ATTR_CONTENT_TYPE = "content-type";

    /**
     * A standard attribute: filename
     */
    public static final String ATTR_FILE_NAME = "filename";

    /**
     * The storage service ID
     */
    public static final String ATTR_SS_ID = "ss_id";

    /**
     * The storage service context path
     */
    public static final String ATTR_SS_CTX = "ss_ctx";

    /**
     * Store the URL point to this sobject
     */
    public static final String ATTR_URL = "url";

    /**
     * Store the content length
     */
    public static final String ATTR_CONTENT_LENGTH = "length";

    /**
     * @return key of this object
     */
    String getKey();

    /**
     * @return length of the object
     */
    long getLength();

    /**
     * Returns URL set to this SObject.
     *
     * 
     *     Calling to this method shall have the same result as
     *     calling {@link #getAttribute(String)} using
     *     {@link ISObject#ATTR_URL}:
     * 
     *
     * 
     *     String url = sobj.getAttribute(ISObject.ATTR_URL);
     * 
     * @return the url to this SObject
     */
    String getUrl();

    /**
     * Return attribute associated with this storage object by key. If there is
     * no such attribute found then null is returned
     *
     * @return the attribute if found or null if not found
     */
    String getAttribute(String key);

    /**
     * Set an attribute to the storage object associated by key specified.
     *
     * @param key attribute key
     * @param val attribute value
     */
    ISObject setAttribute(String key, String val);

    /**
     * Set attributes to the storage object
     *
     * @param attrs
     * @return the object with attributes set
     */
    ISObject setAttributes(Map attrs);

    /**
     * @return true if the storage object has attributes
     */
    boolean hasAttribute();

    /**
     * @return a copy of attributes of this storage object
     */
    Map getAttributes();

    /**
     * Is content is empty
     *
     * @return if the instance is empty
     */
    public boolean isEmpty();

    /**
     * Is this storage object valid. A storage object is not valid
     * if the file/input stream is not readable
     *
     * @return true if this instance is valid or false otherwise
     */
    public boolean isValid();

    /**
     * Return previous exception that cause the sobject invalid
     *
     * @return the previous exception
     */
    public Throwable getException();

    /**
     * @return the the stuff content as an file
     */
    File asFile() throws UnexpectedIOException;

    /**
     * @return the stuff content as a string
     */
    String asString() throws UnexpectedIOException;

    /**
     * @return the stuff content as a string using the charset to encode
     */
    String asString(Charset charset) throws UnexpectedIOException;

    /**
     * @return the stuff content as a byte array
     */
    byte[] asByteArray() throws UnexpectedIOException;

    /**
     * Returns an {@link InputStream} connect to the sobject. Note it is
     * caller's responsibility to close the inputStream
     *
     * @return the stuff content as an input stream
     */
    InputStream asInputStream() throws UnexpectedIOException;

    /**
     * Consume the inputstream of this storage object one time and then close the input stream
     *
     * @param consumer the consumer function
     */
    void consumeOnce($.Function consumer) throws UnexpectedIOException;

    /**
     * Returns {@code true} if this SObject is dumb
     *
     * @return {@code true} if this instance is dumb
     */
    boolean isDumb();

}