package com.perforce.client.api; /** * The Perforce client API. * * The ClientApi class represents a connection with the Perforce server. * * <p> Member functions in this class are used to establish and terminate * the connection with the server, establish the settings and protocols to * use while running commands, and run Perforce commands over the connection. * * <p> I/O is handled by a {@link ClientUser} object, and errors are captured * in a {@link P4Error} object. A <tt>ClientApi</tt> object maintains * information about client-side settings (<tt>P4PORT</tt>, etc.) and protocol * information, such as the server version, and whether "tagged" output is enabled. * * <p> ClientApi does not include any virtual functions, and typically does not * need to be subclassed. * * <p> Any Perforce command that is executed must be invoked through * {@link #run run()} after first opening a connection using {@link #init}. * A single connection can be used to invoke multiple commands by calling * {@link #run run()} multiple times after a single {@link #init}; this approach * provides faster performance than using multiple connections. * * <p> Basic flow: <pre> * <code> * ClientUser ui = new ClientUser(); * ClientApi client = new ClientApi(); * * // setPort(), setProtocol() must happen before the init(). * client.setPort(someFunctionOf(client.getPort())); //optional * client.setProtocol("var", "value"); //optional * * client.init(); * * // getClient() must happen after the init(). * client.setClient(someFunctionOf(client.getClient())); //optional * client.setCwd( someFunctionOf(client.getCwd())); //optional * client.setUser( someFunctionOf(client.getUser())); //optional * * while (!client.droppped())) { * String func = getCommand(); * String argv[] = getCommandArgs(); * client.setArgv(argv); * client.run(func, ui); * } * * client.end(); * </code></pre> */ public class ClientApi { long instance = 0; private static native long nNewInstance(); private static native void nDeleteInstance(long instance); public ClientApi() { this.instance = nNewInstance(); } protected void finalize() { nDeleteInstance(this.instance); this.instance = 0; } // public void setMerger(ClientMerger *m); /** * Asks for special server treatment. * Called before {@link #init}. * * @param p a <code>String</code> value * @param v a <code>String</code> value */ public void setProtocol(String p, String v) { nSetProtocol(this.instance, p, v); } /** * Gets a protocol capability. * Called after {@link #init}. * * @param v a <code>String</code> value * @return a <code>String</code> value */ public String getProtocol(final String v) { return nGetProtocol(this.instance, v); } /** * Sets a variable. * * @param name a <code>String</code> value * @param value a <code>String</code> value */ public void setVar(String name, final String value) { nSetVar(this.instance, name, value); } /** * Sets a variable using var=value syntax. * * @param arg a <code>String</code> value */ public void setVarV(String arg) { nSetVarV(this.instance, arg); } /** * Sets unnamed variables (args for {@link #run run}). * * @param args a <code>String[]</code> value */ public void setArgv(String[] args) { // System.err.println("Args: "); // for (int i = 0; i < args.length; i++) // { // System.err.println(" arg[" + i + "] |" + args[i] + "|"); // } nSetArgv(this.instance, args); } /** * Gets a variable. * * @param name a <code>String</code> value * @return a <code>String</code> value */ public String getVar(final String name) { return nGetVar(this.instance, name); } /** * Establishes connection and prepares to run commands. * * @exception P4ClientException if an error occurs */ public void init() throws P4ClientException { P4Error err = new P4Error(); nInit(this.instance, err.instance); err.checkException(); } /** * Runs a single command. * * @param func a <code>String</code> value * @param ui a <code>ClientUser</code> value */ public void run(String func, ClientUser ui) { // System.err.println("Running " + func); nRun(this.instance, func, ui.instance); } /** * Cleans up end of connection. * * @exception P4ClientException if an error occurs */ public void end() throws P4ClientException { P4Error err = new P4Error(); nEnd(this.instance, err.instance); err.checkException(); } /** * Checks if connection is no longer serviceable. * * @return a <code>boolean</code> value */ public boolean dropped() { return nDropped(this.instance) != 0; } /** * Runs a single command (potentially) asynchronously. * * @param func a <code>String</code> value * @param ui a <code>ClientUser</code> value */ public void runTag(String func, ClientUser ui) { nRunTag(this.instance, func, ui.instance); } /** * Waits for all {@link #runTag runTag} calls to complete. * */ public void waitTag() { nWaitTag(this.instance); } /** * Waits for a {@link #runTag runTag} call to complete. * * <p> Note that commands are still always executed in the order * in which they were placed on the queue, so this method waits * for each command in the queue to return, up to the command * specified by the <var>ui</var< argument. * * @param ui a <code>ClientUser</code> value */ public void waitTag(ClientUser ui) { nWaitTag(this.instance, ui.instance); } private static native void nSetCwd(long instance, String c); /** * Sets current directory, overriding default. * Must be called before {@link #run run} to take effect. * * @param c a <code>String</code> value */ public void setCwd(String c) { nSetCwd(this.instance, c); } /** * Sets client, overriding default. * Must be called before {@link #run run} to take effect. * * @param c a <code>String</code> value */ public void setClient(String c) { nSetClient(this.instance, c); } /** * Sets host, overriding default. * Must be called before {@link #run run} to take effect. * * @param c a <code>String</code> value */ public void setHost(String c) { nSetHost(this.instance, c); } /** * Sets password, overriding default. * Must be called before {@link #run run} to take effect. * * @param c a <code>String</code> value */ public void setPassword(String c) { nSetPassword(this.instance, c); } /** * Sets port, overriding default. * Must be called before {@link #init} to take effect. * * @param c a <code>String</code> value */ public void setPort(String c) { nSetPort(this.instance, c); } private static native void nSetUser(long instance, String c); /** * Sets user, overriding default. * Must be called before {@link #run run} to take effect. * * @param c a <code>String</code> value */ public void setUser(String c) { nSetUser(this.instance, c); } /** * Sets the client in the registry (so as to take permanent effect), * then calls {@link #setClient setClient} to take immediate effect. * * @param c a <code>String</code> value * @exception P4ClientException if an error occurs */ public void defineClient(String c) throws P4ClientException { P4Error err = new P4Error(); nDefineClient(this.instance, c, err.instance); err.checkException(); } /** * Sets the host in the registry (so as to take permanent effect), * then calls {@link #setHost setHost} to take immediate effect. * * @param c a <code>String</code> value * @exception P4ClientException if an error occurs */ public void defineHost(String c) throws P4ClientException { P4Error err = new P4Error(); nDefineHost(this.instance, c, err.instance); err.checkException(); } /** * Sets the password in the registry (so as to take permanent effect), * then calls {@link #setPassword setPassword} to take immediate effect. * * @param c a <code>String</code> value * @exception P4ClientException if an error occurs */ public void definePassword(String c) throws P4ClientException { P4Error err = new P4Error(); nDefinePassword(this.instance, c, err.instance); err.checkException(); } /** * Sets the port in the registry (so as to take permanent effect), * then calls {@link #setPort setPort} to take immediate effect. * * @param c a <code>String</code> value * @exception P4ClientException if an error occurs */ public void definePort(String c) throws P4ClientException { P4Error err = new P4Error(); nDefinePort(this.instance, c, err.instance); err.checkException(); } /** * Sets the user in the registry (so as to take permanent effect), * then calls {@link #setUser setUser} to take immediate effect. * * @param c a <code>String</code> value * @exception P4ClientException if an error occurs */ public void defineUser(String c) throws P4ClientException { P4Error err = new P4Error(); nDefineUser(this.instance, c, err.instance); err.checkException(); } /** * Gets the current directory as determined by defaults or by the * corresponding set value. * * @return a <code>String</code> value */ public String getCwd() { return nGetCwd(this.instance); } /** * Gets the client as determined by defaults or by the * corresponding set value. Valid only after {@link #init} * establishes the connection, because the hostname of the local * endpoint may serve as the default client name. * * @return a <code>String</code> value */ public String getClient() { return nGetClient(this.instance); } /** * Gets the host as determined by defaults or by the * corresponding set value. Valid only after {@link #init} * establishes the connection, because the hostname of the local * endpoint may serve as the default client name. * * @return a <code>String</code> value */ public String getHost() { return nGetHost(this.instance); } /** * Gets the OS as determined by defaults or by the corresponding * set value. * * @return a <code>String</code> value */ public String getOs() { return nGetOs(this.instance); } /** * Gets the password as determined by defaults or by the * corresponding set value. * * @return a <code>String</code> value */ public String getPassword() { return nGetPassword(this.instance); } /** * Gets the port as determined by defaults or by the corresponding * set value. * * @return a <code>String</code> value */ public String getPort() { return nGetPort(this.instance); } /** * Gets the user as determined by defaults or by the corresponding * set value. * * @return a <code>String</code> value */ public String getUser() { return nGetUser(this.instance); } private static native void nSetProtocol(long instance, String p, String v); private static native String nGetProtocol(long instance, final String v); private static native void nSetVar(long instance, String name, final String value); private static native void nSetVarV(long instance, String arg); private static native void nSetArgv(long instance, String[] args); private static native String nGetVar(long instance, final String name); private static native void nInit(long instance, long errorInstance); private static native void nRun(long instance, String func, long clientUserInstance); private static native long nEnd(long instance, long errInstance); private static native long nDropped(long instance); private static native void nRunTag(long instance, String func, long clientUserInstance); private static native void nWaitTag(long instance); private static native void nWaitTag(long instance, long clientUserInstance); private static native void nSetClient(long instance, String c); private static native void nSetHost(long instance, String c); private static native void nSetPassword(long instance, String c); private static native void nSetPort(long instance, String c); private static native void nDefineClient(long instance, String c, long errorInstance); private static native void nDefineHost(long instance, String c, long errorInstance); private static native void nDefinePassword(long instance, String c, long errorInstance); private static native void nDefinePort(long instance, String c, long errorInstance); private static native void nDefineUser(long instance, String c, long errorInstance); private static native String nGetCwd(long instance); private static native String nGetClient(long instance); private static native String nGetHost(long instance); private static native String nGetOs(long instance); private static native String nGetPassword(long instance); private static native String nGetPort(long instance); private static native String nGetUser(long instance); }
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#1 | 4181 | Paul Krause |
Rename //guest/paul_krause/perforce/api/java/wcvm/com/... //guest/paul_krause/perforce/api/java/wcvm/javax/... To //guest/paul_krause/perforce/api/java/wcvm/src-15/... |
||
//guest/paul_krause/perforce/api/java/wcvm/com/perforce/client/api/ClientApi.java | |||||
#4 | 4130 | Paul Krause | Copy Javadoc from Perforce 2003.2 C/C++ API User's Guide. | ||
#3 | 4100 | Paul Krause | fix type problems | ||
#2 | 4091 | Paul Krause | Copy comments from clientapi.h into Javadoc. | ||
#1 | 4073 | Paul Krause | branch com.perforce.api package from michael_bishop | ||
//guest/michael_bishop/P4APIForJava/java/com/perforce/client/api/ClientApi.java | |||||
#1 | 430 | Michael Bishop |
Initial checkin. Seems to work. Not very much testing. Not very much documentation. Some more commenting needs to take place. But, it's there to experiment with. |