Class UpdateProviderSongSession

java.lang.Object

org.jjazz.musiccontrol.api.playbacksession.BaseSongSession

org.jjazz.musiccontrol.api.playbacksession.UpdateProviderSongSession

All Implemented Interfaces:

PropertyChangeListener, EventListener, ControlTrackProvider, EndOfPlaybackActionProvider, PlaybackSession, SongContextProvider, UpdatableSongSession.UpdateProvider

public class UpdateProviderSongSession
extends BaseSongSession
implements UpdatableSongSession.UpdateProvider

A session to be used as a BaseSongSession for an UpdatableSongSession.

The session provides on-the-fly UpdatableSongSession.Updates for:
- chord symbol changes (add/remove/change/moveAll)
- rhythm parameter value changes
- existing user phrase content changes (but not for add/remove user phrase events)
- MidiMix instrument transposition/velocity changes, plus drum keymap and drum rerouting changes

If change can't be handled as an update (eg a song part tempo factor change or a click setting), session is marked dirty (ie needs regeneration). If session is dirty, editors can still show the playback point using the control track but the "dirty" changes are not heard.

A more serious change like a structural change of the song context will make the session dirty, plus it disables the control track and any future update. So editors should stop showing the playback point, and any further change will not be heard (until a new session is generated).

Nested Class Summary

Nested classes/interfaces inherited from interface org.jjazz.musiccontrol.api.playbacksession.PlaybackSession

PlaybackSession.Context, PlaybackSession.State

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_POST_UPDATE_SLEEP_TIME_MS
static final int	DEFAULT_PRE_UPDATE_BUFFER_TIME_MS

Fields inherited from class org.jjazz.musiccontrol.api.playbacksession.BaseSongSession

PLAYBACK_SETTINGS_LOOP_COUNT

Fields inherited from interface org.jjazz.musiccontrol.api.playbacksession.ControlTrackProvider

ENABLED_STATE

Fields inherited from interface org.jjazz.musiccontrol.api.playbacksession.PlaybackSession

PROP_DIRTY, PROP_LOOP_COUNT, PROP_MUTED_TRACKS, PROP_STATE, PROP_TEMPO

Fields inherited from interface org.jjazz.musiccontrol.api.playbacksession.UpdatableSongSession.UpdateProvider

PROP_UPDATE_AVAILABLE, PROP_UPDATE_PROVISION_ENABLED

Method Summary

Modifier and Type	Method	Description
void	close()	Put session in the CLOSED state and release used resources, so that session can be disposed.
void	generate(boolean silent)	Generate the initial music then listen for song changes to be ready to generate updates.
UpdateProviderSongSession	getFreshCopy(SongContext sgContext)	Get a copy of this session in the NEW state for the specified context.
UpdatableSongSession.Update	getLastUpdate()	Get the last available update after the PROP_UPDATE_AVAILABLE property change event was fired.
int	getPostUpdateSleepTimeMs()	Wait time after having generated an update.
int	getPreUpdateBufferTimeMs()	Wait time before starting the music generation to provide an update.
static UpdateProviderSongSession	getSession(SongContext sgContext, PlaybackSession.Context context)	Get a session using the default config with update control enabled.
static UpdateProviderSongSession	getSession(SongContext sgContext, SessionConfig sConfig, boolean enableUpdateControl, PlaybackSession.Context context)	Create or reuse a session for the specified parameters.
boolean	isUpdateControlEnabled()	True if updates are authorized/blocked depending on the PlaybackSettings auto update value.
boolean	isUpdateProvisionEnabled()	Check if this UpdateProvider can still provide updates.
void	propertyChange(PropertyChangeEvent e)
void	setPostUpdateSleepTimeMs(int postUpdateSleepTimeMs)	Calls to this method are ignored if state is not NEW.
void	setPreUpdateBufferTimeMs(int preUpdateBufferTimeMs)	Calls to this method are ignored if state is not NEW.
void	setUserErrorExceptionHandler(Consumer<UserErrorGenerationException> handler)	The handler for exception during music generation due to user error.

Methods inherited from class org.jjazz.musiccontrol.api.playbacksession.BaseSongSession

addPropertyChangeListener, getBarRange, getClickTrackId, getContext, getControlTrack, getEndOfPlaybackAction, getLoopCount, getLoopEndTick, getLoopStartTick, getPrecountTrackId, getRvPhraseMap, getRvTrackIdMap, getSequence, getSessionConfig, getSongContext, getState, getTempo, getTick, getTracksMuteStatus, isDirty, isUseActiveSongBackgroundMusicBuilder, removePropertyChangeListener, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

DEFAULT_PRE_UPDATE_BUFFER_TIME_MS

public static final int DEFAULT_PRE_UPDATE_BUFFER_TIME_MS

See Also:

• MusicGenerationQueue
• Constant Field Values

DEFAULT_POST_UPDATE_SLEEP_TIME_MS

public static final int DEFAULT_POST_UPDATE_SLEEP_TIME_MS

See Also:

• MusicGenerationQueue
• Constant Field Values

Method Details

getSession

public static UpdateProviderSongSession getSession(SongContext sgContext,
 SessionConfig sConfig,
 boolean enableUpdateControl,
 PlaybackSession.Context context)

Create or reuse a session for the specified parameters.

Sessions are cached: if a non-dirty session in the NEW or GENERATED state already exists for the same parameters then return it, otherwise a new session is created.

Parameters:

sgContext -

sConfig -

enableUpdateControl - If true updates are authorized depending on the PlaybackSettings AutoUpdateEnabled value.

context -

Returns:

A session in the NEW or GENERATED state.

getSession

public static UpdateProviderSongSession getSession(SongContext sgContext,
 PlaybackSession.Context context)

Get a session using the default config with update control enabled.

Parameters:

sgContext -

context -

Returns:

A targetSession in the NEW or GENERATED state.

getFreshCopy

public UpdateProviderSongSession getFreshCopy(SongContext sgContext)

Description copied from interface: PlaybackSession

Get a copy of this session in the NEW state for the specified context.

Specified by:

getFreshCopy in interface PlaybackSession

Overrides:

getFreshCopy in class BaseSongSession

Parameters:

sgContext - If null use a copy of this session'SongContext

Returns:

generate

public void generate(boolean silent)
              throws MusicGenerationException

Generate the initial music then listen for song changes to be ready to generate updates.

Specified by:

generate in interface PlaybackSession

Overrides:

generate in class BaseSongSession

Parameters:

silent -

Throws:

MusicGenerationException

close

public void close()

Description copied from interface: PlaybackSession

Put session in the CLOSED state and release used resources, so that session can be disposed.

Specified by:

close in interface PlaybackSession

Overrides:

close in class BaseSongSession

See Also:

• PlaybackSession.PROP_STATE

isUpdateControlEnabled

public boolean isUpdateControlEnabled()

True if updates are authorized/blocked depending on the PlaybackSettings auto update value.

Returns:

getPreUpdateBufferTimeMs

public int getPreUpdateBufferTimeMs()

Wait time before starting the music generation to provide an update.

Returns:

See Also:

• MusicGenerationQueue.getPreUpdateBufferTimeMs()

setPreUpdateBufferTimeMs

public void setPreUpdateBufferTimeMs(int preUpdateBufferTimeMs)

Calls to this method are ignored if state is not NEW.

Parameters:

preUpdateBufferTimeMs -

getPostUpdateSleepTimeMs

public int getPostUpdateSleepTimeMs()

Wait time after having generated an update.

Returns:

See Also:

• MusicGenerationQueue.getPostUpdateSleepTimeMs()

setPostUpdateSleepTimeMs

public void setPostUpdateSleepTimeMs(int postUpdateSleepTimeMs)

Calls to this method are ignored if state is not NEW.

Parameters:

postUpdateSleepTimeMs -

setUserErrorExceptionHandler

public void setUserErrorExceptionHandler(Consumer<UserErrorGenerationException> handler)

The handler for exception during music generation due to user error.

By default the handler displays the exception error message using StatusDisplayer.

Parameters:

handler - If null errors will be ignored

propertyChange

public void propertyChange(PropertyChangeEvent e)

Specified by:

propertyChange in interface PropertyChangeListener

Overrides:

propertyChange in class BaseSongSession

getLastUpdate

public UpdatableSongSession.Update getLastUpdate()

Description copied from interface: UpdatableSongSession.UpdateProvider

Get the last available update after the PROP_UPDATE_AVAILABLE property change event was fired.

Specified by:

getLastUpdate in interface UpdatableSongSession.UpdateProvider

Returns:

Can be null if PROP_UPDATE_AVAILABLE change event was never fired.

isUpdateProvisionEnabled

public boolean isUpdateProvisionEnabled()

Description copied from interface: UpdatableSongSession.UpdateProvider

Check if this UpdateProvider can still provide updates.

Specified by:

isUpdateProvisionEnabled in interface UpdatableSongSession.UpdateProvider

Returns:

True upon this object's creation, but might become false if UpdateProvider is "too" dirty and not able anymore to provide updates.

See Also:

• PlaybackSession.isDirty()