com.softicar.platform.common.io.resource.IResource Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of platform-common Show documentation
The SoftiCAR Platform is a lightweight, Java-based library to create interactive business web applications.
There is a newer version: 50.0.0
package com.softicar.platform.common.io.resource;

import com.softicar.platform.common.core.exceptions.SofticarIOException;
import com.softicar.platform.common.io.StreamUtils;
import com.softicar.platform.common.io.mime.IMimeType;
import com.softicar.platform.common.io.mime.MimeType;
import com.softicar.platform.common.io.resource.hash.ResourceHash;
import com.softicar.platform.common.string.charset.Charsets;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.Charset;
import java.util.Optional;

/**
 * Represents a general resource.
 * 
 * Typical examples of resources include images, CSS files, and exports of
 * generated files.
 *
 * @author Alexander Schmidt
 * @author Oliver Richers
 */
public interface IResource {

	/**
	 * Returns this resource as an input stream.
	 * 

	 * When this resource is requested, the complete data returned by this input
	 * stream is sent to the requester.
	 *
	 * @return input stream with the content of this resource (may be
	 *         null)
	 */
	InputStream getResourceAsStream();

	/**
	 * Returns the mime type of this resource.
	 * 

	 * In case the mime type is unknown, {@link MimeType#getDefaultMimeType()}
	 * may be used.
	 *
	 * @return the mime type (never null)
	 */
	IMimeType getMimeType();

	/**
	 * Returns the character set (i.e. the textual encoding) of this resource,
	 * if any.
	 * 

	 * When a textual resource is converted back and forth between binary and
	 * text, the same character set must be used. This method defines which
	 * character set was used to convert the original text of this resource into
	 * binary data.
	 * 

	 * For example, the character set should be given to an {@link InputStream}
	 * reader, to convert the binary data into text.
	 * 

	 * Returns {@link Optional#empty()} for non-textual resources.
	 *
	 * @return the {@link Charset} that this resource was encoded with
	 */
	Optional getCharset();

	/**
	 * Returns the filename of this resource, if any.
	 * 

	 * For example, if this resource is downloaded through a web browser, the
	 * return value of this method might be used to suggest a filename.
	 *
	 * @return the filename of this resource
	 */
	Optional getFilename();

	/**
	 * Returns an optional {@link ResourceHash} for the content of this
	 * {@link IResource}.
	 * 

	 * The {@link ResourceHash} is over the data provided by the
	 * {@link InputStream} returned from {@link #getResourceAsStream()}. It
	 * uniquely identifies the content, that is, equal content always returns an
	 * equal {@link ResourceHash}. The actual hash algorithm is an
	 * implementation detail and might be a SHA1, MD5 or similar.
	 * 

	 * Since not every implementation is able to provide a {@link ResourceHash}
	 * over its data, the returned value is an {@link Optional} and might be
	 * empty.
	 *
	 * @return the optional {@link ResourceHash} over the content
	 */
	Optional getContentHash();

	/**
	 * Returns the content of this {@link IResource} as UTF-8 encoded text.
	 * 
	 * May only be called on textual resources.
	 *
	 * @return the content as UTF-8 encoded text (never null)
	 */
	default String getContentTextUtf8() {

		try (var inputStream = getResourceAsStream()) {
			return StreamUtils.toString(inputStream, Charsets.UTF8);
		} catch (IOException exception) {
			throw new SofticarIOException(exception);
		}
	}
}