001package Torello.Browser;
002
003import Torello.Browser.AbstractBuilder;
004import Torello.Browser.CommandDescriptor;
005import Torello.Browser.TypeBuilder;
006
007/**
008 * A 'Builder' software design pattern that may be used to construct {@link Script} instances for
009 * CDP browser commands whose method signatures contain long lists of input parameters.  This class
010 * is primarily intended for generated "abbreviated" command methods: zero-argument overloads that
011 * return a pre-configured {@code CommandBuilder}, already connected to the appropriate
012 * {@link CommandDescriptor}.
013 * 
014 * <BR /><BR />
015 * In the generated CDP domain classes, these abbreviated methods are only emitted for commands
016 * that accept 5 or more input parameters.  Shorter command methods should usually be invoked
017 * directly, since the ordinary method call is already clear enough, and no public abbreviated
018 * builder-entry method is generated for them.
019 * 
020 * <BR /><BR />
021 * ⚠️ The main purpose of {@code 'CommandBuilder'} is to avoid long, repetitive invocations filled
022 * with {@code null} placeholders for optional command parameters.
023 * 
024 * <EMBED CLASS='external-html' DATA-FILE-ID=CB.Example>
025 * 
026 * @param <T> The return type produced by the {@link Script} created by this builder's
027 * {@link #build()} method.
028 * 
029 * @see CommandDescriptor
030 * @see Script
031 * @see Promise
032 */
033public class CommandBuilder<T>
034    extends AbstractBuilder<Script<T>>
035    implements java.io.Serializable, Cloneable
036{
037    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
038    protected static final long serialVersionUID = 1L;
039
040    /** 
041     * Convert 'this' Builder-Instance into an actual Object-Instance 
042     * @return A Script
043     */
044    @Override
045    @SuppressWarnings("unchecked")
046    public Script<T> build()
047    {
048        return BuildScript.build
049            ((CommandDescriptor<T>) this.descriptor, this.assignments, this.assigned);
050    }
051
052    // used by 'clone'
053    private CommandBuilder(final CommandBuilder<T> other)
054    { super(other); }
055
056    // used by 'builder'
057    private CommandBuilder(final CommandDescriptor<?> descriptor)
058    { super(descriptor); }
059
060    public static <T> CommandBuilder<T> builder(final CommandDescriptor<T> descriptor)
061    {
062        java.util.Objects.requireNonNull(descriptor, "parameter 'descriptor' is null");
063        return new CommandBuilder<>(descriptor);
064    }
065
066    /** {@inheritDoc} */
067    @Override
068    public CommandBuilder<T> clone()
069    { return new CommandBuilder<>(this); }
070    
071}