com.github.powerlibraries.io.In Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of iopower Show documentation
Power Libraries is a small project to collect some repeatedly needed or otherwise useful Java 8 classes in a collection of tiny libraries. IO Power is the first and really tiny library of the Power Libraries. It contains some simple helper method for opening Input- and Outputstreams. The main purpose of IO Power is to make opening streams, readers and writers less cluttered and simple to understand.
There is a newer version: 1.1.3
Show newest version
package com.github.powerlibraries.io;

import java.io.File;
import java.io.InputStream;
import java.net.URL;
import java.nio.charset.Charset;

import com.github.powerlibraries.io.builder.InBuilder;
import com.github.powerlibraries.io.builder.sources.ByteArraySource;
import com.github.powerlibraries.io.builder.sources.FileSource;
import com.github.powerlibraries.io.builder.sources.InputStreamSource;
import com.github.powerlibraries.io.builder.sources.Source;
import com.github.powerlibraries.io.builder.sources.StringSource;
import com.github.powerlibraries.io.builder.sources.URLSource;

/**
 * This class contains a number of useful static methods that help creating InputStreams and Readers.
 * @author Manuel Hegner
 */
public interface In {
	
	/**
	 * This creates an input of any kind from a {@link File}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * @param file the path to read from
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder file(String file) {
		if(file==null)
			throw new NullPointerException("The given file was null");
		return file(new File(file));
	}
	
	/**
	 * This creates an input of any kind from a {@link File}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * @param parent the path parent to read from
	 * @param child the path child to read from
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder file(File parent, String child) {
		if(parent==null || child==null)
			throw new NullPointerException("The given file was null");
		return file(new File(parent, child));
	}
	
	/**
	 * This creates an input of any kind from a {@link File}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * @param parent the path parent to read from
	 * @param child the path child to read from
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder file(String parent, String child) {
		if(parent==null || child==null)
			throw new NullPointerException("The given file was null");
		return file(new File(parent, child));
	}
	
	/**
	 * This creates an input of any kind from a {@link File}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * @param file the file to read from
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder file(File file) {
		if(file==null)
			throw new NullPointerException("The given file was null");
		return new InBuilder(new FileSource(file));
	}

	/**
	 * This creates an input of any kind from an {@link URL}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * @param resource the resource URL to read from
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder resource(URL resource) {
		if(resource==null)
			throw new NullPointerException("The given resource was null");
		return new InBuilder(new URLSource(resource));
	}
	
	/**
	 * This creates an input of any kind from an {@link URL}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * This call is the same as calling:
	 * 	 * In.resource(referenceClass.getResource(resourceName));
	 * 
	 * @param referenceClass the class used to resolve the resourceName
	 * @param resourceName the name of resource to load (see {@link Class#getResource})
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder resource(Class referenceClass, String resourceName) {
		return resource(referenceClass.getResource(resourceName));
	}
	
	/**
	 * This creates an input of any kind from an {@link URL}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * This call is the same as calling:
	 * 	 * In.resource(In.class.getResource(resourceName));
	 * 
	 * @param resourceName the name of resource to load (see {@link Class#getResource})
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder resource(String resourceName) {
		return resource(In.class.getResource(resourceName));
	}
	
	/**
	 * This creates an input of any kind from an {@link InputStream}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * Be aware that if you use this method you can only build one Input with the Builder. Otherwise the given
	 * stream will be used more than once.
	 * @param inputStream the {@link InputStream} to read from
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder stream(InputStream inputStream) {
		if(inputStream==null)
			throw new NullPointerException("The given inputstream was null");
		return new InBuilder(new InputStreamSource(inputStream));
	}
	
	/**
	 * This creates an input of any kind from a {@link String}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * This method uses the default {@link Charset}
	 * @param str the {@link String} to read from
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder string(String str) {
		if(str==null)
			throw new NullPointerException("The given string was null");
		return new InBuilder(new StringSource(str, Charset.defaultCharset()));
	}
	
	/**
	 * This creates an input of any kind from a {@link String}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * @param str the {@link String} to read from
	 * @param charset the {@link Charset} that should be used to decode the string into bytes
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder string(String str, Charset charset) {
		if(str==null)
			throw new NullPointerException("The given string was null");
		return new InBuilder(new StringSource(str, charset));
	}
	
	/**
	 * This creates an input of any kind from a {@link Source}. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * This method can be used with custom implementations of the {@link Source} interface.
	 * @param source the {@link Source} to read from
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder source(Source source) {
		if(source==null)
			throw new NullPointerException("The given source was null");
		return new InBuilder(source);
	}
	
	/**
	 * This creates an input of any kind from an array of bytes. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * @param bytes the byte array to read from
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder bytes(byte[] bytes) {
		if(bytes==null)
			throw new NullPointerException("The given bytes were null");
		return new InBuilder(new ByteArraySource(bytes));
	}
	
	/**
	 * This creates an input of any kind from an array of bytes. The returned {@link InBuilder} can be used
	 * to specifiy which kind of Reader or InputStream should be created and allows you to specify further how
	 * the input chain is build.
	 * @param bytes the byte array to read from
	 * @param offset the offset in the buffer of the first byte to read
	 * @param length the maximum number of bytes to read from the buffer.
	 * @return an {@link InBuilder} used to specify which kind of input should be created
	 */
	public static InBuilder bytes(byte[] bytes, int offset, int length) {
		if(bytes==null)
			throw new NullPointerException("The given bytes were null");
		return new InBuilder(new ByteArraySource(bytes, offset, length));
	}
}