guacamole chapter 14

12/6/2015 Chapter14.guacamolecommon

http://guacdev.org/doc/gug/guacamolecommon.html 1/4

Chapter14.guacamolecommonTheJavaAPIprovidedbytheGuacamoleprojectiscalledguacamolecommon.Itprovidesabasicmeansoftunneling data between the JavaScript client provided by guacamolecommonjs and the native proxydaemon,guacd.ThereareotherclassesprovidedaswellwhichmakedealingwiththeGuacamoleprotocolandreadingfromguacamole.propertieseasier,butingeneral,thepurposeofthislibraryistofacilitatethecreationofcustomtunnelsbetweentheJavaScriptclientandguacd.

HTTPtunnelThe Guacamole Java API implements the HTTP tunnel using a servlet calledGuacamoleHTTPTunnelServlet. This servlet handles all requests coming to it over HTTP from theJavaScriptclient,andtranslatedthemintoconnect,read,orwriterequests,whicheachgetdispatchedtothedoConnect(),doRead(),anddoWrite()functionsaccordingly.

Normally,youwouldn'ttouchthedoRead()anddoWrite()functions,asthesehavealreadybeenwrittentoproperlyhandletherequestsoftheJavaScripttunnel,andifyoufeeltheneedtotouchthesefunctions,youareprobablybetteroffwritingyourown tunnel implementation,althoughsucha thing isdifficult todo inaperformantway.

When developing an application based on the Guacamole API, you should useGuacamoleHTTPTunnelServletbyextending it, implementing your own version ofdoConnect(), which istheonlyabstractfunctionitdefines.ThetutoriallaterinthisbookdemonstratinghowtowriteaGuacamolebasedwebapplicationshowsthebasicsofdoingthis,butgenerally,doConnect() isanexcellentplaceforauthenticationorothervalidation,asitistheresponsibilityofdoConnect()tocreate(ornotcreate)theactualtunnel.IfdoConnect()doesnotcreatethetunnel,communicationbetweentheJavaScriptclientandguacdcannottakeplace,whichisanidealpowertohaveasanauthenticator.

ThedoConnect() function is expected to "attach" aGuacamoleTunnel to theweb session, abstracted byGuacamoleSession. Attaching a tunnel to the session allows future tunnel requests to retrieve the sametunnelanduseit,thusallowingonetunneltobesplitacrossmultiplerequests.AssumingthedoConnect()function successfully creates the tunnel, it must then return the created tunnel. The alreadyimplementedparts of GuacamoleHTTPTunnelServlet then return the unique identifier of this tunnel to the JavaScriptclient,allowingitsowntunnelimplementationtocontinuetocommunicatewiththetunnelexistingontheJavaside.

Instances of GuacamoleTunnel are created associated with a GuacamoleSocket, which is the abstractinterfacesurroundingthelowlevelconnectiontoguacd.Overall,thereisasocket(GuacamoleSocket)whichprovidesaTCPconnectiontoguacd.ThissocketisexposedtoGuacamoleTunnel,whichprovidesabstractprotocolaccessaroundwhatisactually(butsecretly,throughtheabstractionoftheAPI)aTCPsocket.TheGuacamoleSession allows instances of GuacamoleTunnel to be shared across requests, andGuacamoleHTTPTunnelServletpullsthesetunnelsfromthesessionasnecessarytofulfillrequestsmadebytheJavaScriptclient.

TheGuacamolewebapplicationextendsthistunnelservletinordertoimplementauthenticationatthelowestpossiblelevel,effectivelyprohibitingcommunicationbetweentheclientandanyremotedesktopsunlesstheyhaveproperlyauthenticated.Yourown implementationcanbeconsiderablysimpler,especially if youdon'tneedauthentication:

publicclassMyGuacamoleTunnelServletextendsGuacamoleHTTPTunnelServlet{

@OverrideprotectedGuacamoleTunneldoConnect(HttpServletRequestrequest)throwsGuacamoleException{



//Connecttoguacdhere(thisisaSTUB)GuacamoleSocketsocket;

//EstablishthetunnelusingtheconnectedsocketGuacamoleTunneltunnel=newGuacamoleTunnel(socket);

//AttachtunneltosessionGuacamoleSessionsession=newGuacamoleSession(httpSession);session.attachTunnel(tunnel);

//Returnpreattachedtunnelreturntunnel;

}

}

UsingtheGuacamoleprotocolguacamolecommonprovidesbasic lowlevelsupport for theGuacamoleprotocol.This lowlevelsupport isleveraged by the HTTP tunnel implementation to satisfy the requirements of the JavaScript clientimplementation,astheJavaScriptclientexpectsthehandshakeproceduretohavealreadytakenplace.Thissupport exists through the GuacamoleReader and GuacamoleWriter classes, which are similar to Java'sReaderandWriterclasses,exceptthattheydealwith theGuacamoleprotocolspecifically,andthushaveslightlydifferentcontracts.

GuacamoleReader

GuacamoleReaderprovidesaverybasicread() functionwhichisrequiredtoreturnoneormorecompleteinstructions inachar array. It also provides the typicalavailable() function,which informs youwhetherread() is likely to block the next time it is called, and an even more abstract version of read() calledreadInstruction() which returns one instruction at a time, wrapped within a GuacamoleInstructioninstance.

Normally, you would not need to use this class yourself. It is used by ConfiguredGuacamoleSocket tocomplete theGuacamoleprotocolhandshakeprocedure,and it isusedbyGuacamoleHTTPTunnelServletwithindoRead()toimplementthereadinghalfofthetunnel.

The only concrete implementation ofGuacamoleReader isReaderGuacamoleReader, which wraps a JavaReader, using that as the source for data to parse into Guacamole instructions. Again, you would notnormallydirectlyusethisclass,norinstantiateityourself.Aworking,concreteinstanceofGuacamoleReadercanberetrievedfromanyGuacamoleSocketorGuacamoleTunnel.

GuacamoleWriter

GuacamoleWriter provides a very basic write() function and a more abstract version calledwriteInstruction()whichwritesinstancesofGuacamoleInstruction.Thesefunctionsareanalogoustotheread()andreadInstruction()functionsprovidedbyGuacamoleReader,andhavesimilarrestrictions:thecontractimposedbywrite()requiresthatwritteninstructionsbecomplete

The only concrete implementation ofGuacamoleWriter isWriterGuacamoleWriter, which wraps a JavaWriter,usingthatasthedestinationforGuacamoleinstructiondata,butyouwouldnotnormallydirectlyusethisclass,norinstantiateityourself.ItisusedbyConfiguredGuacamoleSockettocompletetheGuacamoleprotocol handshake procedure, and it is used by GuacamoleHTTPTunnelServlet within doWrite() toimplementthewritinghalfofthetunnel.

Ifnecessary,aGuacamoleWritercanberetrievedfromanyGuacamoleSocketorGuacamoleTunnel,butinmostcases,theclassesprovidedbytheGuacamoleJavaAPIwhichalreadyuseGuacamoleWriterwillbesufficient.



ReadingpropertiesThe Guacamole Java API provides simple access to guacamole.properties for convenience, althoughsuchsupportisnotstrictlyrequired.ThissupportisprovidedthroughtheGuacamoleProperiesutilityclass,which cannot be instantiated and provides two simple property retrieval functions: getProperty() andgetRequiredProperty(), thedifferencebeingthat the formercanreturnnull ifaproperty isnotdefined,whilethelatterwillthrowanexceptioninstead.ThesefunctionsaregenericandtypesafeandwillreturnthecorrectJavaclassortypewhengivenaninstanceofaproperty.

InGuacamole,eachpropertyisdeclaredasanimplementationofGuacamoleProperty,andmustprovideanimplementation of getName(), which returns the name of the property as it should exist withinguacamole.properties,andparseValue(),whichisgiventheStringvalueofthepropertyasreadfromguacamole.properties,andmust return thedeclared typeof theGuacamoleProperty implementation. Agood example of how this works is the IntegerGuacamoleProperty implementation included withinguacamolecommon:

publicabstractclassIntegerGuacamolePropertyimplementsGuacamoleProperty{

@OverridepublicIntegerparseValue(Stringvalue)throwsGuacamoleException{

//Ifnopropertyprovided,returnnull.if(value==null)returnnull;

try{Integerinteger=newInteger(value);returninteger;}catch(NumberFormatExceptione){thrownewGuacamoleServerException("Property\""+getName()+"\"mustbeaninteger.",e);}

}

}

Notice that this implementation does not actually provide getName(). Instead, it only implementsparseValue(),theintentbeingtomakeotherdevelopers'liveseasierwhentheyneedtoretrieveanintegerpropertyfromguacamole.properties.Usingthisclass,retrievinganintegerpropertyissimple:

publicclassMyClass{

publicstaticfinalIntegerGuacamolePropertyIMPORTANT_INT=newIntegerGuacamoleProperty(){

@OverridepublicStringgetName(){return"importantint";}

};

}

...lateronwithinMyClass...

intimportant=GuacamoleProperties.getRequiredProperty(IMPORTANT_INT);



guacamolecommonprovidesacoupleofsimilarclassesforretrievingcommontypesofproperties,suchasaString orFile, and implementing your own to facilitate properties that parse into arrays or aList, etc.shouldbereasonablysimple.

guacamole chapter 14

Documents