<commit_before>package matlabcontrol;

/*
 * Copyright (c) 2011, <NAME>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
 * following conditions are met:
 *  - Redistributions of source code must retain the above copyright notice, this list of conditions and the following
 *    disclaimer.
 *  - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
 *    following disclaimer in the documentation and/or other materials provided with the distribution.
 *  - Neither the name of matlabcontrol nor the names of its contributors may be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * Allows for Java to communicate with a running MATLAB session. This class cannot be instantiated, instead it can be
 * created by using a {@link MatlabProxyFactory}.
 * <br><br>
 * This proxy is thread-safe. While methods may be called concurrently, they will be completed sequentially on MATLAB's
 * main thread. More than one proxy may be interacting with MATLAB (for instance one proxy might be running inside
 * MATLAB and another might be running outside MATLAB) and their interactions will not occur simultaneously. Regardless
 * of the number of proxies, interaction with MATLAB occurs in a single threaded manner.
 * <br><br>
 * <strong>Running outside MATLAB</strong><br>
 * Proxy methods that are relayed to MATLAB may throw exceptions. They will be thrown if:
 * <ul>
 * <li>an internal MATLAB exception occurs*</li>
 * <li>communication between this JVM and the one MATLAB is running in is disrupted (likely due to closing MATLAB)</li>
 * <li>the class of the object to be returned is not {@code java.io.Serializable}</li>
 * <li>the class of the object to be sent or returned is not defined in the JVM receiving the object</li>
 * </ul>
 * <strong>Running inside MATLAB</strong><br>
 * Proxy methods that are relayed to MATLAB may throw exceptions. They will be thrown if:
 * <ul>
 * <li>an internal MATLAB exception occurs*</li>
 * <li>the method call is made from the Event Dispatch Thread (EDT) used by AWT and Swing components
 *     (This is done to prevent MATLAB from becoming non-responsive or hanging indefinitely. To get around this
 *     limitation the {@link matlabcontrol.extensions.MatlabCallbackInteractor} can be used.)</li>
 * </ul>
 * *Internal MATLAB exceptions occur primarily for two reasons:
 * <ul>
 * <li>There is an error in the MATLAB code executing. An example of this includes attempting to call a function that
 *     does not exist (frequently due to a typo).</li>
 * <li>The Java MATLAB Interface (JMI) becoming out of sync with MATLAB. An example of this is an exception being thrown
 *     when attempting to retrieve or make use of a variable that has already been defined.</li>
 * </ul>
 * 
 * @author <a href="mailto:<EMAIL>"><NAME></a>
 */
public class MatlabProxy implements MatlabInteractor<Object>
{
    /* Internal implementation notes:
     * 
     * This class could really be designed as an interface, or even an abstract class. It has intentionally not been.
     * It is not an interface to prevent users of the matlabcontrol API from making their own proxies, as being able to
     * know for sure what the MatlabProxy actually is, is a useful guarantee. To prevent this, this class could instead
     * be an abstract class with a package private constructor. This was not done to conceptually simplify the API. By
     * making this class appear to be THE proxy it effectively hides the complexity that comes from even thinking about
     * the difference between running inside MATLAB or outside MATLAB. Making this a concrete class is similar to how
     * MatlabProxyFactory is really just a wrapper around the two real factories. While this class is not a wrapper, the
     * end result is extremely similar.
     */
    
    /**
     * This constructor is package private to prevent subclasses from outside of this package.
     */
    MatlabProxy() { }
    
    /**
     * Whether this proxy is connected to MATLAB.
     * <br><br>
     * The most likely reasons for this method to return {@code false} is if MATLAB has been closed or the factory that
     * created this proxy has been shutdown.
     * 
     * @return 
     */
    public boolean isConnected()
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }
    
    /**
     * Returns the unique identifier for this proxy.
     * <br><br>
     * If this proxy was created by a call to {@link MatlabProxyFactory#requestProxy()}, then the {@code String} this
     * method returns matches that returned when calling to create this proxy.
     * 
     * @return identifier
     */
    public String getIdentifier()
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }
    
    /**
     * Whether this proxy is connected to a session of MATLAB that was running previous to the request to create this
     * proxy.
     * 
     * @return 
     */
    public boolean isExistingSession()
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }
   
    //The following methods are overridden so that they appear in the javadocs

    @Override
    public void eval(String command) throws MatlabInvocationException
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }

    @Override
    public void exit() throws MatlabInvocationException
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }

    @Override
    public void feval(String functionName, Object[] args) throws MatlabInvocationException
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }

    @Override
    public Object getVariable(String variableName) throws MatlabInvocationException
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }

    @Override
    public Object returningEval(String command, int returnCount) throws MatlabInvocationException
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }

    @Override
    public Object returningFeval(String functionName, Object[] args) throws MatlabInvocationException
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }

    @Override
    public Object returningFeval(String functionName, Object[] args, int returnCount) throws MatlabInvocationException
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }

    @Override
    public void setDiagnosticMode(boolean enable) throws MatlabInvocationException
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }

    @Override
    public void setVariable(String variableName, Object value) throws MatlabInvocationException
    {
        throw new UnsupportedOperationException("Must be implemented in subclass");
    }
}<commit_msg>Changes MatlabProxy to an abstract class.<commit_after>package matlabcontrol;

/*
 * Copyright (c) 2011, <NAME>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
 * following conditions are met:
 *  - Redistributions of source code must retain the above copyright notice, this list of conditions and the following
 *    disclaimer.
 *  - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
 *    following disclaimer in the documentation and/or other materials provided with the distribution.
 *  - Neither the name of matlabcontrol nor the names of its contributors may be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * Allows for Java to communicate with a running MATLAB session. This class cannot be instantiated, instead it can be
 * created by using a {@link MatlabProxyFactory}.
 * <br><br>
 * This proxy is thread-safe. While methods may be called concurrently, they will be completed sequentially on MATLAB's
 * main thread. More than one proxy may be interacting with MATLAB (for instance one proxy might be running inside
 * MATLAB and another might be running outside MATLAB) and their interactions will not occur simultaneously. Regardless
 * of the number of proxies, interaction with MATLAB occurs in a single threaded manner.
 * <br><br>
 * <strong>Running outside MATLAB</strong><br>
 * Proxy methods that are relayed to MATLAB may throw exceptions. They will be thrown if:
 * <ul>
 * <li>an internal MATLAB exception occurs*</li>
 * <li>communication between this JVM and the one MATLAB is running in is disrupted (likely due to closing MATLAB)</li>
 * <li>the class of the object to be returned is not {@code java.io.Serializable}</li>
 * <li>the class of the object to be sent or returned is not defined in the JVM receiving the object</li>
 * </ul>
 * <strong>Running inside MATLAB</strong><br>
 * Proxy methods that are relayed to MATLAB may throw exceptions. They will be thrown if:
 * <ul>
 * <li>an internal MATLAB exception occurs*</li>
 * <li>the method call is made from the Event Dispatch Thread (EDT) used by AWT and Swing components
 *     (This is done to prevent MATLAB from becoming non-responsive or hanging indefinitely. To get around this
 *     limitation the {@link matlabcontrol.extensions.MatlabCallbackInteractor} can be used.)</li>
 * </ul>
 * *Internal MATLAB exceptions occur primarily for two reasons:
 * <ul>
 * <li>There is an error in the MATLAB code executing. An example of this includes attempting to call a function that
 *     does not exist (frequently due to a typo).</li>
 * <li>The Java MATLAB Interface (JMI) becoming out of sync with MATLAB. An example of this is an exception being thrown
 *     when attempting to retrieve or make use of a variable that has already been defined.</li>
 * </ul>
 * 
 * @author <a href="mailto:<EMAIL>"><NAME></a>
 */
public abstract class MatlabProxy implements MatlabInteractor<Object>
{
    /* Internal implementation notes:
     * 
     * This class could really be designed as an interface. It has intentionally not been. It is not an interface to
     * prevent users of the matlabcontrol API from making their own proxies, as being able to know for sure what the
     * MatlabProxy actually is, is a useful guarantee.
     */
    
    /**
     * This constructor is package private to prevent subclasses from outside of this package.
     */
    MatlabProxy() { }
    
    /**
     * Whether this proxy is connected to MATLAB.
     * <br><br>
     * The most likely reasons for this method to return {@code false} is if MATLAB has been closed or the factory that
     * created this proxy has been shutdown.
     * 
     * @return if connected
     */
    public abstract boolean isConnected();
    
    /**
     * Returns the unique identifier for this proxy.
     * <br><br>
     * If this proxy was created by a call to {@link MatlabProxyFactory#requestProxy()}, then the {@code String} this
     * method returns matches that returned when calling to create this proxy.
     * 
     * @return identifier
     */
    public abstract String getIdentifier();
    
    /**
     * Whether this proxy is connected to a session of MATLAB that was running previous to the request to create this
     * proxy.
     * 
     * @return if existing session
     */
    public abstract boolean isExistingSession();
   
    //The following methods are overridden so that they appear in the javadocs

    @Override
    public abstract void eval(String command) throws MatlabInvocationException;

    @Override
    public abstract void exit() throws MatlabInvocationException;

    @Override
    public abstract void feval(String functionName, Object[] args) throws MatlabInvocationException;

    @Override
    public abstract Object getVariable(String variableName) throws MatlabInvocationException;

    @Override
    public abstract Object returningEval(String command, int returnCount) throws MatlabInvocationException;

    @Override
    public abstract Object returningFeval(String functionName, Object[] args) throws MatlabInvocationException;

    @Override
    public abstract Object returningFeval(String functionName, Object[] args, int returnCount) throws MatlabInvocationException;

    @Override
    public abstract void setDiagnosticMode(boolean enable) throws MatlabInvocationException;

    @Override
    public abstract void setVariable(String variableName, Object value) throws MatlabInvocationException;
}
{'fraction_non_alphanumeric': 0.061452902328814736, 'fraction_numerical': 0.0005561348627042057, 'mean_word_length': 3.6707792207792207, 'pattern_counts': {'":': 0, '<': 87, '<?xml version=': 0, '>': 87, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6979781', 'n_tokens_mistral': 3645, 'n_tokens_neox': 3406, 'n_words': 1775}