universum.studios.android.intent

Class ContentIntent<I extends ContentIntent<I>>

java.lang.Object

universum.studios.android.intent.BaseIntent<I>

universum.studios.android.intent.ContentIntent<I>

Direct Known Subclasses:

ImageIntent, VideoIntent

public abstract class ContentIntent<I extends ContentIntent<I>>
extends BaseIntent<I>

A BaseIntent builder implementation providing base API for building and starting of intents targeting a content previewing/editing/obtaining related applications.

The content intent may be intent to obtain or preview specific type of content, like image, audio, video, .... To decide which type of intent (obtain/preview) should be started, the current set of ContentIntent.ContentHandler is checked, if it isn't empty an OBTAIN intent will be started, so chooser dialog will be showed with a list items specific for each of current providers. If there are no providers assigned to this intent builder and there was specified valid Uri to input(Uri), a PREVIEW intent will be started.

Since:

1.0

Author:

Martin Albedinsky

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ContentIntent.ContentHandler A ContentHandler is a simple class that may be used to add one item into ContentIntent builder.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONTENT_FILE_TIME_STAMP_FORMAT Name format for files created by this type of intent.

Constructor Summary

Constructors

Constructor and Description
ContentIntent()

Method Summary

Modifier and Type	Method and Description
android.content.Intent	build(android.content.Context context) Called to create an instance of Intent from the current data of this intent builder.
static File	createContentFile(String fileName, File directory) Creates a new file with the given parameters within the specified directory.
static File	createContentFile(String fileName, String externalDirectoryType) Same as createContentFile(String, File) with directory obtained via Environment.getExternalStoragePublicDirectory(String) with the specified externalDirectoryType as type.
static String	createContentFileTimeStamp() Creates a time stamp in the CONTENT_FILE_TIME_STAMP_FORMAT format for the current Date that may be used as name for a content file.
String	dataType() Returns the content's data (MIME) type.
I	dataType(String type) Sets a data (MIME) type for the content uri.
protected void	ensureCanBuildOrThrow() Called to ensure that this builder can build its Intent from its current data.
List<ContentIntent.ContentHandler>	handlers() Returns the list of content handlers to be displayed in a chooser dialog.
I	input(File file) Same as input(Uri) with uri created from the given file if not null.
I	input(android.net.Uri uri) Sets an Uri to a content that should be previewed by an activity that can handle/preview the content of the data type specified via dataType(String).
protected android.content.Intent	onBuild(android.content.Context context) Will be invoked only if there are no content handlers assigned to this intent builder.
protected void	onShowChooserDialog(IntentStarter starter) Invoked from startWith(IntentStarter) to show a chooser dialog if there is at least one ContentIntent.ContentHandler attached.
protected boolean	onStartWith(IntentStarter starter, android.content.Intent intent) Invoked whenever BaseIntent.startWith(IntentStarter) is called and there is an activity available that can handle the given intent that has been created via BaseIntent.build(Context).
I	output(File file) Same as output(Uri) with uri created from the given file if not null.
I	output(android.net.Uri uri) Sets an Uri where should be stored a content provided by an activity that can handle/provide the content of the data type specified via dataType(String).
boolean	startWith(IntentStarter starter) Starts na intent specific for this intent builder created via BaseIntent.build(Context) using the given intent starter.
android.net.Uri	uri() Returns the uri passed either via input(Uri) or via output(Uri).
abstract ContentIntent	withDefaultHandlers(android.content.Context context) Attaches default content handlers to this intent.
I	withHandler(ContentIntent.ContentHandler handler) Adds the specified content handler item into the list of handlers.
I	withHandlers(ContentIntent.ContentHandler... handlers) Same as withHandlers(List) for variable array of ContentHandlers.
I	withHandlers(List<ContentIntent.ContentHandler> handlers) Same as withHandler(ContentHandler) for list of handler items.

Methods inherited from class universum.studios.android.intent.BaseIntent

activityNotFoundMessage, activityNotFoundMessage, cannotBuildIntentException, dialogTitle, dialogTitle, enterTransition, enterTransition, exitTransition, exitTransition, isActivityForIntentAvailable, notifyActivityNotFound, transitions

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONTENT_FILE_TIME_STAMP_FORMAT

public static final String CONTENT_FILE_TIME_STAMP_FORMAT

Name format for files created by this type of intent.

Constant Value: yyyyMMdd_HHmmss

See Also:

Constant Field Values

Constructor Detail

ContentIntent

public ContentIntent()

Method Detail

createContentFileTimeStamp

@NonNull
public static String createContentFileTimeStamp()

Creates a time stamp in the CONTENT_FILE_TIME_STAMP_FORMAT format for the current Date that may be used as name for a content file.

Returns:

String representation of the current time stamp.

createContentFile

@Nullable
public static File createContentFile(@NonNull
                                               String fileName,
                                               @NonNull
                                               String externalDirectoryType)

Same as createContentFile(String, File) with directory obtained via Environment.getExternalStoragePublicDirectory(String) with the specified externalDirectoryType as type.

Parameters:

fileName - The desired name for the requested file.

externalDirectoryType - One of Environment.DIRECTORY_PICTURES, Environment.DIRECTORY_MOVIES, ..., external directory types.

createContentFile

@Nullable
public static File createContentFile(@NonNull
                                               String fileName,
                                               @NonNull
                                               File directory)

Creates a new file with the given parameters within the specified directory.

Parameters:

fileName - The desired name for the requested file. Must also contain a suffix for the file.

directory - The directory within which should be the requested file created.

Returns:

New instance of the desired file or null if some IO error occurs during its creation process.

See Also:

createContentFile(String, String)

withDefaultHandlers

public abstract ContentIntent withDefaultHandlers(@NonNull
                                                  android.content.Context context)

Attaches default content handlers to this intent.

Type and count of default handlers may differ depending on a specific ContentIntent implementation.

Returns:

This intent builder to allow methods chaining.

withHandlers

public I withHandlers(@NonNull
                      ContentIntent.ContentHandler... handlers)

Same as withHandlers(List) for variable array of ContentHandlers.

Parameters:

handlers - The desired array of handlers to add.

withHandlers

public I withHandlers(@Nullable
                      List<ContentIntent.ContentHandler> handlers)

Same as withHandler(ContentHandler) for list of handler items.

Parameters:

handlers - The desired list of handlers items to add. May be null to clear the current one.

Returns:

This intent builder to allow methods chaining.

withHandler

public I withHandler(@NonNull
                     ContentIntent.ContentHandler handler)

Adds the specified content handler item into the list of handlers. These handler items will be used to build a chooser dialog with list of these items (if any) so a user may choose one of them to handle a specific content intent. Such dialog is created and showed whenever content intent is started via startWith(IntentStarter) and there is at least one handler item.

Parameters:

handler - The desired handler item to add.

Returns:

This intent builder to allow methods chaining.

See Also:

withHandlers(ContentHandler...), withDefaultHandlers(Context), handlers()

handlers

@NonNull
public List<ContentIntent.ContentHandler> handlers()

Returns the list of content handlers to be displayed in a chooser dialog.

Returns:

List of handlers or Collections.EMPTY_LIST if no content handlers has been added yet.

See Also:

withHandler(ContentHandler), withHandlers(List), withDefaultHandlers(Context)

input

public I input(@Nullable
               File file)

Same as input(Uri) with uri created from the given file if not null.

Parameters:

file - The desired file to be used to crate input Uri. May be null to clear the current input uri.

input

public I input(@Nullable
               android.net.Uri uri)

Sets an Uri to a content that should be previewed by an activity that can handle/preview the content of the data type specified via dataType(String). The specified Uri will be attached to an intent build via build(Context) if there are no content handlers attached to this intent builder.

Note, that the current data type will be set to null, so dataType(String) should be called immediately after a new Uri is set. A specific implementations of this ContentIntent builder may here specify a default data type.

Parameters:

uri - The desired uri, which should be delivered to the handling activity. May be null to clear the current one.

Returns:

This intent builder to allow methods chaining.

See Also:

uri()

output

public I output(@Nullable
                File file)

Same as output(Uri) with uri created from the given file if not null.

Parameters:

file - The desired file to be used to crate Uri. May be null to clear the current output uri.

output

public I output(@Nullable
                android.net.Uri uri)

Sets an Uri where should be stored a content provided by an activity that can handle/provide the content of the data type specified via dataType(String). The specified Uri will be attached to an intent of one of content handlers attached to this intent builder.

Parameters:

uri - The desired uri. May be null to clear the current one.

Returns:

This intent builder to allow methods chaining.

See Also:

uri()

uri

@Nullable
public android.net.Uri uri()

Returns the uri passed either via input(Uri) or via output(Uri).

Returns:

Current uri or null if there was no uri specified yet.

dataType

public I dataType(@NonNull
                  String type)

Sets a data (MIME) type for the content uri.

Parameters:

type - The desired MIME type for the uri specified via input(Uri).

Returns:

This intent builder to allow methods chaining.

See Also:

dataType()

dataType

@Nullable
public String dataType()

Returns the content's data (MIME) type.

Returns:

MIME type for the uri specified via input(Uri) or null if no data type has been specified yet.

See Also:

dataType(String)

startWith

public boolean startWith(@NonNull
                         IntentStarter starter)

Description copied from class: BaseIntent

Starts na intent specific for this intent builder created via BaseIntent.build(Context) using the given intent starter.

Overrides:

startWith in class BaseIntent<I extends ContentIntent<I>>

Parameters:

starter - The desired starter to be used to start the intent. See IntentStarters for default available starters.

Returns:

True if the intent has been successfully started, false otherwise.

onShowChooserDialog

protected void onShowChooserDialog(@NonNull
                                   IntentStarter starter)

Invoked from startWith(IntentStarter) to show a chooser dialog if there is at least one ContentIntent.ContentHandler attached.

Parameters:

starter - The intent starter that may be used to access context and also to start intent for a selected content handler from the chooser dialog.

build

@NonNull
public android.content.Intent build(@NonNull
                                             android.content.Context context)

Description copied from class: BaseIntent

Called to create an instance of Intent from the current data of this intent builder.

Overrides:

build in class BaseIntent<I extends ContentIntent<I>>

Parameters:

context - Context obtained from the IntentStarter.

Returns:

An instance of Intent specific for this intent builder.

Throws:

IllegalStateException - If there is at least one ContentIntent.ContentHandler attached.

ensureCanBuildOrThrow

protected void ensureCanBuildOrThrow()

Description copied from class: BaseIntent

Called to ensure that this builder can build its Intent from its current data.

If there are some required data missing/not specified, an exception indicating such state should be thrown. The default exception may be created via BaseIntent.cannotBuildIntentException(String).

Overrides:

ensureCanBuildOrThrow in class BaseIntent<I extends ContentIntent<I>>

onBuild

@NonNull
protected android.content.Intent onBuild(@NonNull
                                                  android.content.Context context)

Will be invoked only if there are no content handlers assigned to this intent builder.

Specified by:

onBuild in class BaseIntent<I extends ContentIntent<I>>

Parameters:

context - Context obtained from the IntentStarter.

Returns:

Intent instance with current data.

onStartWith

protected boolean onStartWith(@NonNull
                              IntentStarter starter,
                              @NonNull
                              android.content.Intent intent)

Description copied from class: BaseIntent

Invoked whenever BaseIntent.startWith(IntentStarter) is called and there is an activity available that can handle the given intent that has been created via BaseIntent.build(Context).

This implementation always returns true.

Overrides:

onStartWith in class BaseIntent<I extends ContentIntent<I>>

Parameters:

starter - The starter with which to start the intent.

intent - The intent instance created by this intent builder.

Returns:

True to indicate that the intent has been started, false otherwise.