/*******************************************************************************
* Copyright (c) 2013, Perforce Software
* 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.
* 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.
******************************************************************************/
package com.perforce.p4java.extension.server;
import java.io.InputStream;
import java.util.Map;
import com.perforce.p4java.client.IClient;
import com.perforce.p4java.extension.command.Request;
import com.perforce.p4java.extension.exception.ServerAccessException;
import com.perforce.p4java.extension.exception.ServerConnectionException;
import com.perforce.p4java.extension.exception.ServerErrorException;
import com.perforce.p4java.server.IOptionsServer;
/**
* A single connection (or potential connection, if disconnected) to a Perforce
* server.
*/
public interface Server {
/**
* Establish a connection to the back end P4D.
*
* This does not login to the back end P4D, but merely establishes the
* connection.
*
* @throws ServerConnectionException
* if there is a network-related issue in connecting to the
* server.
*/
void connect() throws ServerConnectionException;
/**
* Establish a connection to the back end P4D as a specific user.
*
* This does not login to the back end P4D, but merely establishes the
* connection as the user. Caches the user credentials so if we need to
* authenticate/re-authenticate we will try later
*
* @throws ServerConnectionException
* if there is a network-related issue in connecting to the
* server.
*/
void connectAs(PrincipalCredential user) throws ServerConnectionException,
ServerAccessException;
/**
* Establish a connection to the back end P4D as a specific user.
*
* This does not login to the back end P4D, but merely establishes the
* connection as the user.
*
* @throws ServerConnectionException
* if there is a network-related issue in connecting to the
* server.
*/
void connectAs(String user) throws ServerConnectionException,
ServerAccessException;
/**
* Log in to the back end P4D. Will connect first if this is not already
* connected, so there is no need to {code Server.connect} prior to {code
* login}.
*
* @param user
* the PrincipalCredential representing the user and password to
* connect as. Never null.
* @throws ServerConnectionException
* if there is a network-related issue in connecting to the
* server.
* @throws ServerAccessException
* if the PrincipalCredential is invalid or incorrect.
* @throws ServerErrorException
* if the P4D returns any other server error.
*/
void login(PrincipalCredential user) throws ServerConnectionException,
ServerAccessException, ServerErrorException;
/**
* for super users, pretend you are someone else
*
* @param user
* - user name to login as
* @throws ServerConnectionException
* @throws ServerAccessException
* @throws ServerErrorException
*/
void loginAs(String user) throws ServerConnectionException,
ServerAccessException, ServerErrorException;
/**
* for super users, deauthenticate as "user"
*
* @param user
* @throws ServerConnectionException
* @throws ServerAccessException
* @throws ServerErrorException
*/
void logoutAs(String user) throws ServerConnectionException,
ServerAccessException, ServerErrorException;
/**
* Prepare the Server for reuse by wiping state, etc.
*/
void clean();
/**
* Log out the current user
*/
void logout();
/**
* Disconnect from the back end P4D.
*/
void disconnect();
/**
* @return true if this is connected to the back end; false otherwise.
*/
boolean isConnected();
/**
* @return the {@code LoginStatus} of this. Never null.
*/
LoginStatus getLoginStatus();
/**
* @return the login name of the currently logged in user. May be null if
* not logged in.
*/
String getLoginName();
/**
* @return the {@code ServerLocation} of this. Never null.
*/
ServerLocation getServerLocation();
/**
* Set the client to be used for client-based operations.
*
* @param client
* the IClient to configure this Server with. never null.
* @throws ServerConnectionException
* @throws ServerErrorException
* @throws ServerAccessException
*/
void setIClient(IClient client) throws ServerConnectionException,
ServerErrorException, ServerAccessException;
/**
* Clear the client associated with this Server
*
* @throws ServerAccessException
* @throws ServerErrorException
* @throws ServerConnectionException
*/
void clearClient() throws ServerConnectionException, ServerErrorException,
ServerAccessException;
/**
* Get the client that is currently configured for this Server connection.
*
* @return the current Client, or null if none is configured
*/
IClient getIClient();
/**
* @return true if the Server has a client configured; false otherwise.
*/
boolean isConfiguredWithClient();
/**
* Execute a given {@code Request} against this server. This would typically
* be called from within the Request itself, which would then process the
* results into a model object or other more palatable format.
*
* @param command
* the Request representing the P4D command to execute
* @return a raw Map output from the server. Never null, but may be empty.
* @throws ServerConnectionException
* if there is a network-related issue in connecting to the
* server.
* @throws ServerAccessException
* if the logged in user is not authorized for this command.
* @throws ServerErrorException
* if the P4D returns any other server error.
*/
Map<String, Object>[] execute(Request command)
throws ServerConnectionException, ServerAccessException,
ServerErrorException;
/**
* Execute a given {@code Request} against this server. This would typically
* be called from within the Request itself, which would then process the
* results into a model object or other more palatable format.
*
* @param command
* the Request representing the P4D command to execute
* @return a raw InputStream output from the server. Never null.
* @throws ServerConnectionException
* if there is a network-related issue in connecting to the
* server.
* @throws ServerAccessException
* if the logged in user is not authorized for this command.
* @throws ServerErrorException
* if the P4D returns any other server error.
*/
InputStream executeStreamCommand(Request command)
throws ServerConnectionException, ServerAccessException,
ServerErrorException;
/**
* Return the current Perforce authentication ticket being used by this
* Server.
*/
String getAuthTicket();
/**
* Return the Perforce authentication ticket for use at the following host
*
* @throws ServerErrorException
* @throws ServerAccessException
*/
String getAuthTicket(String hostIP) throws ServerErrorException,
ServerAccessException;
/**
* Return the IOptionsServer wrapped by this connection.
*/
IOptionsServer getIOptionsServer();
/**
* Returns whether the connection will be to a unicode server
*/
boolean isUnicode();
/**
* user should have the username/p4 ticket set to be passed on to the
* server's connection
*
* @param user
* @throws ServerConnectionException
* @throws ServerAccessException
* @throws ServerErrorException
*/
void loginAs(PrincipalCredential user) throws ServerConnectionException,
ServerAccessException, ServerErrorException;
}