OAG KeyPropertiesStore

Oracle Fusion Middleware
OracleAPIGatewayKeyPropertyStoreUserGuide
11gRelease2(11.1.2.4.0)
July2015
OracleAPIGatewayKeyPropertyStoreUserGuide,11gRelease2(11.1.2.4.0)
Copyright1999,2015,Oracleand/oritsaffiliates.Allrightsreserved.
Thissoftwareandrelateddocumentationareprovidedunderalicenseagreementcontainingrestrictionsonuseand
disclosureandareprotectedbyintellectualpropertylaws.Exceptasexpresslypermittedinyourlicenseagreementorallowed
bylaw,youmaynotuse,copy,reproduce,translate,broadcast,modify,license,transmit,distribute,exhibit,perform,
publish,ordisplayanypart,inanyform,orbyanymeans.Reverseengineering,disassembly,ordecompilationofthis
software,unlessrequiredbylawforinteroperability,isprohibited.
Theinformationcontainedhereinissubjecttochangewithoutnoticeandisnotwarrantedtobeerror-free.Ifyoufindany
errors,pleasereportthemtousinwriting.
IfthissoftwareorrelateddocumentationisdeliveredtotheU.S.GovernmentoranyonelicensingitonbehalfoftheU.S.
Government,thefollowingnoticeisapplicable:
U.S.GOVERNMENTRIGHTSPrograms,software,databases,andrelateddocumentationandtechnicaldatadeliveredtoU.S.
Governmentcustomersare"commercialcomputersoftware"or"commercialtechnicaldata"pursuanttotheapplicable
FederalAcquisitionRegulationandagency-specificsupplementalregulations.Assuch,theuse,duplication,disclosure,
modification,andadaptationshallbesubjecttotherestrictionsandlicensetermssetforthintheapplicableGovernment
contract,and,totheextentapplicablebythetermsoftheGovernmentcontract,theadditionalrightssetforthinFAR52.227-
19,CommercialComputerSoftwareLicense(December2007).OracleUSA,Inc.,500OracleParkway,RedwoodCity,CA
94065.
Thissoftwareisdevelopedforgeneraluseinavarietyofinformationmanagementapplications.Itisnotdevelopedor
intendedforuseinanyinherentlydangerousapplications,includingapplicationswhichmaycreateariskofpersonalinjury.If
youusethissoftwareindangerousapplications,thenyoushallberesponsibletotakeallappropriatefail-safe,backup,
redundancy,andothermeasurestoensurethesafeuseofthissoftware.OracleCorporationanditsaffiliatesdisclaimany
liabilityforanydamagescausedbyuseofthissoftwareindangerousapplications.
OracleisaregisteredtrademarkofOracleCorporationand/oritsaffiliates.Othernamesmaybetrademarksoftheirrespective
owners.
Thissoftwareanddocumentationmayprovideaccesstoorinformationoncontent,products,andservicesfromthirdparties.
OracleCorporationanditsaffiliatesarenotresponsibleforandexpresslydisclaimallwarrantiesofanykindwithrespectto
third-partycontent,products,andservices.OracleCorporationanditsaffiliateswillnotberesponsibleforanyloss,costs,or
damagesincurredduetoyouraccesstooruseofthird-partycontent,products,orservices.Thisdocumentationisin
prereleasestatusandisintendedfordemonstrationandpreliminaryuseonly.Itmaynotbespecifictothehardwareonwhich
youareusingthesoftware.OracleCorporationanditsaffiliatesarenotresponsibleforandexpresslydisclaimallwarrantiesof
anykindwithrespecttothisdocumentationandwillnotberesponsibleforanyloss,costs,ordamagesincurredduetothe
useofthisdocumentation.
Theinformationcontainedinthisdocumentisforinformationalsharingpurposesonlyandshouldbeconsideredinyour
capacityasacustomeradvisoryboardmemberorpursuanttoyourbetatrialagreementonly.Itisnotacommitmentto
deliveranymaterial,code,orfunctionality,andshouldnotberelieduponinmakingpurchasingdecisions.Thedevelopment,
release,andtimingofanyfeaturesorfunctionalitydescribedinthisdocumentremainsatthesolediscretionofOracle.
Thisdocumentinanyform,softwareorprintedmatter,containsproprietaryinformationthatistheexclusivepropertyof
Oracle.YouraccesstoanduseofthisconfidentialmaterialissubjecttothetermsandconditionsofyourOracleSoftware
LicenseandServiceAgreement,whichhasbeenexecutedandwithwhichyouagreetocomply.Thisdocumentand
informationcontainedhereinmaynotbedisclosed,copied,reproduced,ordistributedtoanyoneoutsideOraclewithout
priorwrittenconsentofOracle.Thisdocumentisnotpartofyourlicenseagreementnorcanitbeincorporatedintoany
contractualagreementwithOracleoritssubsidiariesoraffiliates.
27July2015
Contents
Preface 6
Whoshouldreadthisdocument 6
Howtousethisdocument 6
1 Introduction to KPS 8
KPSarchitecture 8
KPSdatastores 9
KPSclientapplications 9
WhentouseaKPS 9
2 Get started with KPS 10

ExampleKPStable 10
Beforeyoubegin 11
DefineKPSconfigurationwithPolicyStudio 11
Step1:Definewheredatawillbestored 11
Step2:DefinetheKPStable 12
Step3:Defineapolicythataccessesthetable 14
Step4:Deploytheconfiguration 16
AddKPSdatausingAPIGatewayManager 17
AccessKPSdatafromapolicy 18
EnableAPIGatewaytracing 19
3 Configure KPS in Policy Studio 20

ConfigureaKPScollection 20
ConfigureaKPStable 21
KPSaliases 22
KPSdatasources 22
KPStablestructure 22
Querytablesusingpropertiesandkeys 23
Primarykey 23
Secondarykey 24
Auto-generatedproperties 24
Encryptedproperties 24
4 Access KPS data using selectors 26

KPSselectorsyntax 26
KPSselectorexamples 27
Oracle API Gateway11.1.2.4.0 Key Property Store User Guide3

5 Manage a KPS using kpsadmin 28
Startkpsadmin 28
Startinverbosemode 28
Selectkpsadminoperations 28
Tableoperations 29
Tableadministrationoperations 29
Collectionadministrationoperations 30
Cassandraadministrationoperations 31
Generaladministrationoperations 31
Exampleswitchingdatasource 31
Step1:Backupcollectiondatausingkpsadmin 31
Step2:Createanewdatasource 32
Step3:Deploytheconfiguration 33
Step4:Restorecollectiondatausingkpsadmin 33
6 Configure Apache Cassandra KPS storage 34

Cassandraconfiguration 34
Cassandraports 35
cassandra.yaml 35
client.yaml 35
jvm.xml 36
Secureports 36
Cassandralogging 36
Cassandraconfigurationsteps 37
Step1:ConfiguretheCassandratopology 37
Step2:StartAPIGatewayswithembeddedCassandraservers 43
Step3:ConfiguretheCassandrareplicationfactor 43
Step4:Configurerequestconsistencylevels 45
DisableCassandrastorage 45
7 Configure database KPS storage 47

Shareddatabasestorage 47
Step1:CreateaKPSdatabasetable 47
Step2:Setupanexternalconnectiontothedatabase 48
Step3:UsetheexternalconnectioninaKPScollection 48
Per-tabledatabasestorage 51
Mapadatabasetableusingasinglekey 51
Howtomapadatabasetableusingacompositekey 56
8 Configure file-based KPS storage 59

Configureafile-basedKPScollection 59
Appendix A: KPS FAQ 60

KPSandAPIGateway 60

WhatisKPSusedforinAPIGateway? 60
WhatisKPSnotsuitablefor? 60
WhatarethetransactionsemanticsofKPS? 60
WhatistheKPScollectionaliasprefixfor? 60
Whyaresomecollectionshidden?Howcanyoushowthem? 61
HowdoIchangeAPIGatewaygrouppassphrase? 61
KPSstorageoptions 62
IsApacheCassandrastoragerequired?Canyouusefileordatabase? 62
HowdoyouswitchstorageforaKPScollection? 62
Whyusedatabasestorage? 62
Whyusefilestorage? 62
Whencanyouusekpsadmin?Whenshouldyouusestorage-specifictools? 63
ApacheCassandra 63
WhyuseCassandraasaKPSstorageoption? 63
WhatversionofCassandradoestheAPIGatewayuse? 63
Whatdoesallhostpollsmarkeddownmean? 63
CanyouuseanexternalCassandrainstance? 63
HowdoyousetCassandraconsistencylevels? 64
HowdoyoudisableCassandra? 64
Appendix B: Troubleshoot KPS error messages 65

Allplatforms 65
Allhostpollsmarkeddown 65
Nodetoolreportsfailedtoconnect 65
Maynotbeenoughreplicaspresenttohandleconsistencylevel 66
Windowsonly 66
Noderunninginclientmode 66
UTF-8charactersnotdisplayingcorrectlyinkpsadmin 67
FSUTILutilitybug 67
Pathlengthissue>255characters 67
Couldnotdropkpskeyspaceusingcassandra-cli 68
Appendix C: Apache Cassandra operations for API Gateway 69

nodetoolrepair 69
Backupandrecovery 69
BackupandrestoreCassandranodedata 69
BackupAPIGatewayKPSconfiguration 70
BackupAPIGatewayCassandraconfigurationanddata 70
Replacedeadnode 70
Further information 72
Glossary 73

Preface

ThisdocumentdescribeshowtoconfigureandmanagetheAPIGatewayKeyPropertyStore(KPS).
TheKPSenablesyoutomanageAPIGatewaydatareferencedfrompoliciesrunningonthe
APIGateway.
Who should read this document

TheintendedaudienceforthisdocumentisKPSadministratorsandpolicydevelopers.Formore
detailsonAPIGatewayuserroles,seetheAPIGatewayConceptsGuide.Thisdocumentassumes
thatyouarefamiliarwiththefollowing:
l Databaseconceptssuchastables,rows,andkeys
l APIGatewayconfigurationanddeployment
l APIGatewayselectors
l Usingcommandlinetools
l Databaseconfigurationwheredatabasestorageisrequired
FormoredetailsonAPIGatewayconfigurationandselectors,seetheAPIGatewayPolicyDeveloper
Guide.
How to use this document

ThisdocumentshouldbeusedwiththeotherdocumentsintheAPIGatewaydocumentationset.
Beforeyoubegin,reviewthisdocumentthoroughly.Thefollowingisabriefdescriptionofthe
contentsofeachchapter:
l IntroductiontoKPSonpage8providesanoverviewoftheKPSarchitectureandfeatures.
l GetstartedwithKPSonpage10explainshowtodevelopanexampleKPStableformanaging
simpleuserinformation.
l ConfigureKPSinPolicyStudio onpage20providesmoredetailonhowtodefinegeneralKPS
configurationusingtheP olicyStudiographicaltool.
l AccessKPSdatausingselectorsonpage26explainshowtoaccessdatainpoliciesonthe
APIGatewayatruntime.
l ManageaKPSusingkpsadminonpage28explainshowtomanageaKPS,independentofdata
source.
l ConfigureApacheCassandraKPSstorageonpage34explainshowtostoreKPSdatainthe
defaultCassandraserverembeddedintheAPIGateway.

Preface
l ConfiguredatabaseKPSstorageonpage47explainshowtostoreKPSdatainarelational
database(forexample,Oracle,MySQL,IBMDB2,orMicrosoftSQLServer).
l Configurefile-basedKPSstorageonpage59explainshowtostoreKPSdatainadirectoryonthe
filesystem.

Introduction to KPS
1
AKeyPropertyStore(KPS)isatableofdatathatcanbereferencedfrompoliciesrunningonthe
APIGateway.DatainaKPStableisassumedtobereadfrequentlyandseldomwritten,andcanbe
changedwithoutincurringanAPIGatewayserviceoutage.KPStablesaresharedacrossan
APIGatewayg roup.
KPS architecture
Thefollowingdiagramshowsasimplerole-basedarchitecture:
AKPSistypicallyusedtostorepropertyvaluesthatareusedinp oliciesrunningonanAPIGateway.
KPSdataisinjectedintopoliciesusingselectorsthatarefirstcreatedinPolicyStudiobypolicy
developers.Selectorsareevaluatedandexpandeddynamicallyatruntime.Forexample,aKPStable
couldcontainauthorizationtokensfordifferentusers.Apolicycouldlookupthetokenforthe
currentuserandinsertitintoanHTTPrequest.
KPStablesareorganizedintocollections.Thetablesinacollectiontypicallyhavesomesortof
relationshiptooneanother.Forexample,theOAuthcollectioncontainsasetoftablesthatstoreall
OAuth-relateddata.EveryKPStableisassignedanaliassothatitc anbeeasilyreferredtoinapolicy
oraRESTrequest.KPSc ollectionsandtablescanbecreatedbypolicydevelopersusingP olicy
Studio.
KPSadministratorscanusetheAPIGatewayManagerwebconsoletoviewandmodifyKPSdataat
runtime.Thisisabusinessoroperationalrolethatmanagesdynamicpolicyconfigurationdataina
KPS(forexample,customerdetails,authorizationlevels,orquotas).Thismeansthatthis
informationdoesnotneedtobeconfiguredatdesigntimebypolicydevelopers.
FormoredetailsonAPIGatewayarchitecture,components,androles,seetheAPIGateway
ConceptsGuide.

1 Introduction to KPS
KPS data stores

KPSdatacanbestoredinoneofthefollowinglocations:
l EmbeddedApacheCassandradatabase:Datacanbedistributedacrossmultiplenodestop rovide
highavailability(thisisthedefaultKPSdatastore).
l Relationaldatabase:AccessibletoallAPIGatewayinstancesintheAPIGatewaygroup.
l JSONfiles:Onthelocalfilesystem.
KPS client applications

APIGatewayp rovidesthefollowingclientapplications:
l PolicyStudio:EnablespolicydeveloperstocreateKPScollectionsandtables,andtoconfigure
datasources.
l APIGatewayManager:Includesavisualweb-basedinterfacetoenableKPSadministratorsto
viewandmodifyKPSdataatruntime.
l kpsadminc ommand:SupportsKPSdataentryandotheradministrativefunctions.Itisdesigned
foruseinadevelopmentenvironment.
l KPSRESTAPI:Enablesremotep rogrammaticclientstoreadandwriteKPSdata.
When to use a KPS

KPSprovidesaflexibledatastorageservicethatcanbeusedtostoreanyconfigurationdata.Its
primaryfunctionistomakethisd ataavailabletoselectorsatruntime,anditisoptimizedforthis
purpose.Thismakesitmostsuitablefordatawiththefollowingc haracteristics:
l DataiscommontoallAPIGatewaysinanAPIGatewaygroup.KPSisnotsuitablefordatathatis
specifictooneparticularAPIGateway.
l Thedataschemaisrelativelysimple.EachKPStableisassumedtobeindependentofallothers,
andreferentialintegrityacrosstablesisnotsupported.
l DatacanchangewhileAPIGatewaysarerunning.UpdatingCassandra-backedordatabase-
backedKPStablesdoesnotrequireanAPIGatewayrestart.Changeabledatashouldthereforebe
storedinKPSinsteadofhard-codedintop olicies.
l Queriesalwaysinvolvelookingupakeyvalueinatabletoretrieveasingleobject.Thisisthe
usagemodelsupportedbyselectors.Adhocqueriesthatinvolvesearchingfornon-key
propertiesarenotsupported.
l Multi-operationtransactionsarenotrequired.EachreadorwritetoaKPStableisconsidereda
standaloneoperation.Lockingorrollbackacrossmultipleoperationsarenotsupported.

Get started with KPS
2
ThistopicexplainshowtodevelopanexampleKPStableformanagingsimpleuserinformation.
Example KPStable
ThefinalstructureoftheexampletableisdisplayedinPolicyStudioasfollows:
Thistablestructureisdescribedasfollows:
Column Type Description
age java.lang.Integer Userage.
email java.lang.String Useremailaddress.ThisisselectedinPolicyStudioasa

uniquePrimary Key,whichisindexedimplicitlyby
default.
firstName java.lang.String Userfirstname.
lastName java.lang.String Usersurname.
password java.lang.String Userpassword,whichisselectedasEncryptedin

PolicyStudio.
ExampletabledataisdisplayedontheSettings>Key Property StorestabintheAPIGateway

Managerwebconsole:

2 Get started with KPS
Before you begin

Thefollowingprerequisitestepsapplytothisexample:
1. EnsurethatanAPIGatewayandanAdminNodeManagerarerunning.
2. StartPolicyStudio,andconnecttotheAdminNodeManager.
Formoredetails,seetheAPIGatewayInstallationGuide.
Define KPS configuration with Policy

Studio
ThemainstepsforconfiguringKPStablesinPolicyStudioareasfollows:
1. Definewherethedatawillbestored.
2. DefinetheKPStable.
3. Defineapolicythataccessesthetable.
4. Deploytheconfiguration.
Step 1: Define where data will be stored

YoumustfirstcreateaKPScollectioninwhichtostoretheKPStableconfiguration.Performthe
followingsteps:
1. InthePolicyStudiotree,sselectKey Property Stores,andselectAdd KPS Collection.
2. IntheAdd KPS Collectiondialog,namethecollectionSamples.

3. SelectaDefault data sourceofEmbedded (Cassandra)foralltablesinthecollection.

Note LeavetheAlias prefixfieldblank.
Step 2: Define the KPS table

Tocreateatable,performthefollowingsteps:
1. InthePolicyStudiotree,right-clickthenewly-createdSamplescollection,andselectAdd
Table:
2. Inthedialog,enteraNameofUser,andprovideaDescription.
3. ClickAddtoassignanaliasofUsertothistable.Atablemusthaveatleastonealias.

4. Nextdefinethetablestructure.Thisconsistsofthetablecolumnsandthedatatypestoredin
eachcolumn.SelecttheUsertableandStructuretab,andclickAdd:
5. Repeattoaddthefollowingcolumnsforyourtablestructureinthe Add Propertydialog:

l email
l password
l firstName
l lastName
l age
Note agehasanInteger(numeric)Type.AlltheothercolumnsareString.
5. WhenyouselecttheUsertable,youshouldhavethefollowingstructure:

6. Youwanttheemailfieldtobetheprimarykeyforthetable,soselectPrimary Keyforthis
field.
7. Youwantthepasswordfieldtobeencryptedwhenstoredinthedatasource,soselect
Encryptedforthisfield.
Step 3: Define a policy that accesses the

table
Todefineatestpolicythataccessesthetable,performthefollowingsteps:
1. AddatestpolicywithaSet MessagefilterfromtheConversionfiltercategory.

2. Right-clickthefilter,andsetitastheStartfilterforthepolicy.
3. EnterafilterContent-Typeoftext/plain.
4. Enterthefollowing Message Bodyforuseinthepolicy:
========================
User
===
Email:${kps.User[http.querystring.id].email}
FirstName:${kps.User[http.querystring.id].firstName}
LastName:${kps.User[http.querystring.id].lastName}
Age:${kps.User[http.querystring.id].age}
========================
ThesesettingsaredisplayedasfollowsintheSet Messagefilter:
Themessagebodyvaluearespecifiedusingselectors,whichareevaluatedandexpanded
dynamicallyatruntime.Forexample,theuserageisspecifiedusingthefollowingselectorstring:
${kps.User[http.querystring.id].age}
Theselectorpartsareexplainedasfollows:
Selector part Description
${ Indicatesthestartoftheselectorusinga{bracket.

Selector part Description
kps SpecifiesthatselectorshouldqueryaKPStable.
.User Specifiesthealiasofthetabletoquery(inthiscase,User).
[ Indicatesthestartofatablepropertyreferenceusinga[bracket.
http.querystring.id ThisisadynamicquerybasedonanHTTPquerystringparameterof
id.Theprimarykeyvalueisretrievedfromthisparameter.Therow
withthiskeyvalueisreturnedfromtheUsertableifitexists.
] Indicatestheendofatablepropertyreferenceusinga]bracket.
.age Retrievestheagecolumn.
} Indicatestheendoftheselectorusinga}bracket.
Note AddaReflect Messagefilter(Conversioncategory)toreturnasuccessfulHTTP

responsestatusof200.
5. Setupapathtothispolicy.Inthisexample,thepathis/kpsGetViaSelector:
Step 4: Deploy the configuration

Whenyouarefinishedwithyourconfigurationchanges,youmustdeploythemtotheAPIGateway.
Todeploythenewconfiguration,clickDeployinthePolicyStudiotoolbar:
ThispushestheconfigurationtotheAPIGatewaygroup.
Tip Ifyoudeployanincorrectconfiguration(forexample,specifyanincorrectprimarykey,
propertytype,orname)youcanusethekpsadmincommandtodropthetableinstorage.
Formoredetails,seeManageaKPSusingkpsadminonpage28.

Add KPS data using API Gateway Manager

YoucanuseAPIGatewayManagertopopulatetheUsertablewithdata.
Performthefollowingsteps:
1. ToaccessAPIGatewayManagerinyourbrowser,gotohttps://localhost:8090.
2. SelecttheSettings>Key Property Storestab.
3. SelecttheSamples>Usertable.
4. Toenternewrecords,selectActions >New Entry:
5. ClickSavetosavearecord.
Forexample,thetableshouldlookasfollows:

Access KPS data from a policy

Forexample,toaccessKPSdatafromapolicy,gotothefollowingURLinyourbrowser:
http://localhost:8080/kpsGetViaSelector?id=patrica.allen@acme.com
ThisURLspecifiestheuserID(email)aspatrica.allen@acme.com
Youmustspecifyanemailthatexistsinyourdata.Forexample:
Note Ifyouenteranemailthatdoesnotexist,youwillsee[invalidfield]results.For
example:

Enable APIGateway tracing

ToenableAPIGatewaydebugtracing,performthefollowingstepsinPolicyStudio:
1. Inthetreeontheleft,selectServer Settings> General.

2. SelectaTracing levelofDEBUG.
3. ClickSave.
4. ClickDeploy.
Note ThissettingenablesdebugtracingfortheentireAPIGateway,andnotjustfortheKPS.
FormoredetailsonAPIGatewaytracingandlogging,seetheAPIGatewayAdministratorGuide.

Configure KPS in Policy
Studio 3
ThistopicdescribeshowtodefinegeneralKPSconfigurationinP olicyStudio.Fordetailsondata
source-specificconfiguration,seethefollowingtopics:
l ConfigureApacheCassandraKPSstorageonpage34
l ConfiguredatabaseKPSstorageonpage47
l Configurefile-basedKPSstorageonpage59
Configure a KPS collection

AKPScollectionisasetofrelatedKPStables.ToconfigureaKPScollection,performthefollowing
steps:
1. Right-clickKey Property StoresinthePolicyStudiotree,andselectAdd Key Property

Store.
2. Specifythefollowingsettingsinthedialog:
l Name:AcollectionmusthaveauniquenameintheAPIGatewayg roup.
l Description:Youcanprovideanoptionaldescription.
l Alias prefix:Youc analsospecifyanaliasprefix,butinnormalusage,youc anleavethis
fieldblank.
l Default data source:Acollectionhasadefaultdatasourcewherealldataforalltablesin
thecollectionisstored.Youcanchangethisdatasourceorassignadifferentdatasourceto
individualtablesinthec ollection.
3. Whenthecollectioniscreated,youcanspecifyaCacheforstorageandretrievalofselector
results.Thiswillimproveselectorreadp erformanceforstoragebackendssuchasdatabases.For
moredetailso nAPIGatewayc aching,seetheAPIGatewayPolicyDeveloperGuide
Note Onlylocalcachesaresupported.

3 Configure KPS in Policy Studio
ThefollowingshowsaKPScollectioncreatedinPolicyStudio:
Configure a KPS table

AKPStableisauser-definedtablemanagedbytheKPSintheAPIGateway.ToconfigureaKPS
table,performthefollowingsteps:
1. Right-clickaKPScollectioninthePolicyStudiotree,andselectAdd Table.
2. Specifythefollowingsettingsinthedialog:
l Name:AKPStablemusthaveauniquenameinthecollection.
l Description:Youcanprovideanoptionaldescription.
l Override the default data source with the following:Youcanspecifyadifferent
datasourcethanthecollectionifrequired.
3. Whenthetableiscreated,ifrequired,youcanusetheOverride the default data source
with the followingsettingtospecifyadifferentdatasourcethanthecollection:

4. Finally,clicktheStructuretab,andclickAddtodefinethestructureofthedatastoredinthe
table.Fordetailsonsupportedtypesandkeys,seethefollowing:
l KPStablestructureonpage22
l Querytablesusingpropertiesandkeysonpage23
KPS aliases
KPStablesareaccessedbyalias.Atablemusthaveatleastonealias.Aliasesmustbeuniqueinan
APIGatewayg roup.Youalsocanusetheoptionalaliasprefixforthecollectiontohelpensurethat
thealiasisunique.
Thefullaliasofatableisthecollectionaliasprefixandthetablealiascombined.Forexample,
samplesandUserg ivessamplesUser.Ifunspecified,thedefaultvalueofthealiasprefixforthe
collectionisanemptystring(forexample,Usero nly).
KPS data sources

AKPScollectionhasoneactivedatasourceassociatedwithit.Alltablesinthecollectionusethis
datasourcebydefault.Youcanc onfigureatabletouseadifferentdatasourceifrequired(see
ConfigureaKPStableonpage21).
KPS table structure

Whencreatingatable,youmustdefinethestructureofthedatathatisstoredinthattable.This
consistsofproperty(column)namesandtypes.Youcanchoosefromthefollowingtypes.

Type Description
String Javatype.
Boolean
Byte
Integer
Long
Double
List JavaListofanyoneoftheaboveJavatypes.
Map JavaMap.ThekeycanbeanyoneoftheaboveJavatypes.Thevaluecanbe
anyoneoftheaboveJavatypes.
Query tables using properties and keys

Youcandirectlyaccessrecordsinatablebyspecifyingcertainp ropertynamesandvalues,without
needingtoreadalltherecordsinthetable.YoucanuseonlypropertiesofString,Long,and
Integertypesforthispurpose.Thesepropertiesareknownasindexableproperties.
Indexedpropertiesincludeprimarykeys,secondarykeys(whichareindexedimplicitly),ando ther
propertiesthatyouexplicitlyselectasIndexedinPolicyStudio.
Primary key
Youcandirectlyaccessanyrecordusingitsprimarykey.Allrecordsinthetablemustbeaccessible
usingauniqueprimarykey.YoumustselectonePrimary KeypertableinPolicyStudio.The
specifiedpropertymustbeanindexableproperty.Primarykeyvaluescannotbenull.

Secondary key
Youcanoptionallyaccessanyrecorddirectlyusingauniquesecondarykey.Thesecondarykeycan
beasimplekey(forexample,email) oracompositekey(forexample,appIdo rcompanyId) .
Thespecifiedpropertiesmustbeindexableproperties.Thesecondarykey(andpartsofacomposite
secondarykey)cannotbenull.Youcanspecifyonesecondarykeypertable.Acommonusecaseis
tospecifyaninternaluniqueIDasasprimarykey,andanexternaluserfacingIDasasecondarykey.
Forexample,idforinternalprimarykey,andemailforexternalIDasasecondarykey.
Selector access
YoucanaccessrecordsinaKPStableusinganAPIGatewayselector.Ifasecondarykeyisdefined
forthetable,youmustspecifyallsecondarykeyvaluesintheselector.Ifnosecondarykeyis
defined,youmustspecifytheprimarykeyvalueinstead.InPolicyStudio,youcanspecifya
secondarykeyoraprimarykeyintheUse the following property name(s) for looking up a
table from a selectorfield.
ForexamplesofaccessingKPStablesusingselectors,seethefollowing:
l GetstartedwithKPSonpage10
l AccessKPSdatausingselectorsonpage26
l ConfiguredatabaseKPSstorageonpage47
Auto-generated properties
InPolicyStudio,youcanselectthatStringfieldsareAutogenerated.Whenarecordiscreated,a
Javajava.util.UUIDisassignedtothefieldifitisempty.
Note Valuesforauto-generatedfieldscanbesuppliedandmodifiedbyusers.KPSo nlygenerates

avalueatcreationtimeifnovalueisalreadyp resent.
Encrypted properties
InPolicyStudio,youcanselectthatStringfieldsareEncryptedinstorage.However,fields
selectedasIndexed(includingprimaryandsecondarykeyfields)cannotbeencrypted.Youcan
entervaluesforencryptedfieldsusingtheAPIGatewayManagerorthekpsadminc ommand.These
valuesareforwardedtotheAPIGatewayintheclearusingtheKPSRESTservice,andencrypted
beforebeingwrittentostorage.
Note TheKPSRESTservicemustalwaysrunoverHTTPS(thedefault).Youmustsetan
encryptionpassphrasefortheAPIGatewaygroup,becausethisisusedintheencryption
process.Formoredetails,seetheAPIGatewayAdministratorGuide.
WhenKPStablesareaccessedusingAPIGatewayselectorsatruntime,encryptedfieldsare
automaticallydecrypted.Selectorsdonotneedtobeawarethatparticularfieldsinatableare
encryptedinstorage.

WhenKPStablesarereadusingtheRESTAPI,dataisalwaysreturnedinitsencryptedstate.
SometimesyoumayneedtoviewdecrypteddatatohelpdebugproblemsonanAPIGateway.You
candothisusingdebugmodeinkpsadmin.Thisrequiresyoutoenterthepassphraseforthe
APIGatewaygroup.
Ifthein-builtKPSencryptionmechanismdoesnotsuityourneeds,youcanencryptandd ecrypt
dataoutsidetheKPS.Inthiscase,youshouldnotselectpropertiesinKPStablesasencryptedin
PolicyStudio.Encrypteddatamustbestring-encodedforstorage(forexample,base64-encoded).
Selectorsthataccessthedatamustdecryptitthemselves(forexample,usingad edicatedd ecryption
filterinPolicyStudio).

Access KPS data using
selectors 4
DatainKPStablescanbeaccessedusingselectorsthatexecuteinpoliciesontheAPIGatewayat
runtime.ThistopicexplainsKPSselectorsyntaxandprovidessomeexampleselectors.
KPS selector syntax

KPSselectorsyntaxisasfollows:
${kps.alias[key].property
Thepartsintheselectoraredescribedasfollows:
Selector Description
part
${ Indicatesthestartoftheselectorusinga{bracket.
kps SpecifiesthatselectorshouldqueryaKPStable.
.alias SpecifiesthefullaliasoftheKPStable,includingthecollectionaliasp refixifany

(forexample,User).
[ Indicatesthestartofatablepropertyreferenceusinga[bracket.
key Thekeyvaluetoquerythetable(forexample,http.querystring.id).
] Indicatetheendofatablepropertyreferenceusinga]bracket.
. Thefieldtoretrievefromthereturnedrow(forexample,age).
property
} Indicatetheendoftheselectorusinga}bracket.
Youcanalsouseacompositekey,forexample:
${kps.alias[key1][key2].property}

4 Access KPS data using selectors
KPS selector examples

ForanexampleofaccessingKPSdatafromaselectorusingaprimarykey,seeGetstartedwithKPS
onpage10.Forexamplesofselectorsthatusebothprimaryandcompositekeys,seeConfigure
databaseKPSstorageonpage47.
ThefollowingtableshowsmoreexamplesofKPSselectors:
Selector Description
${kps.User l GetrowfromKPStablewithUseralias
[http.querystring.id].firstName}
l UsekeysuppliedinHTTPquerystring
(id)
l ReturnfirstNamefieldofrow
["kathy.adams@acme.com"].age}
l Useconstantkey
"kathy.adams@acme.com"with
quotationmarks
l Returnagefieldofrow

[http.querystring.firstName]
l UsekeysuppliedinHTTPquerystring

[http.querystring.lastName].email}
(firstNameandlastName)

l Returnemailfieldofrow
Formoredetailsonselectors,seetheAPIGatewayPolicyDeveloperGuide.

Manage a KPS using
kpsadmin 5
Thekpsadmincommand-linetoolprovidesKPSmanagementfunctions,independentofdata
source.Thistoolisespeciallyusefulfordevelopmentuse.
Note Inproduction,youshouldusedatasource-specifictoolsandadministrationproceduresfor
databackup,restore,security,optimization,monitoring,andsoon.
Start kpsadmin
Fromacommandprompt,startkpsadmin.Forexample:
Windows
INSTALL_DIR\Win32\bin\kpsadmin.bat
UNIX
INSTALL_DIR/posix/bin/kpsadmin
Start in verbose mode

Torunkpsadmininverbosemode,usethe-voption.kpsadminwillthenshowallRESTmessages
thatareexchangedwiththeAPIGateway.Thisisusefulfordebugging.Forexample:
kpsadmin-v
Select kpsadmin operations

Thissectiondescribesthekpsadminoperationsthatareavailable.Whenyoufirstselectan
operation,youmustenterthefollowing:
l APIGatewaygrouptouse
l AdminAPIGatewayinthatgroupthathandlesKPSrequests
Note ThisistheAdminAPIGatewayusedforKPSpurposesonly,andshouldnotbeconfused
withtheAdminNodeManager.

5 Manage a KPS using kpsadmin
l KPScollectiontouseinthegroup
l KPStabletouseinthecollection
Youcanchangethisselectionatanytime.
Table operations
Thekpsadmintableoperationsareasfollows:
Table operation Description
CreateRow Createarowintheselectedtable.
ReadRow Readarowbyprimarykeyintheselectedtable.
UpdateRow Updatearowintheselectedtable.Therowisspecifiedbyprimarykey.
DeleteRow Deletearowintheselectedtable.Therowisspecifiedbyprimarykey.
ListRows Listallrowsinthetable.
Table administration operations

Thekpsadminoperationsfortableadministrationareasfollows:
Table Description
Administration
Clear Clearallrowsinthetable.
Backup Backupthetabledata.ThegeneratedbackupUUIDisrequiredwhen
restoringthedata.
Restore Restoretabledata.Thetablemustbeemptybeforeyourestore.
Re-encrypt Re-encryptencrypteddatainthetable.Usethisoptionwhenthe
encryptionpassphrasehasbeenchangedfortheAPIGatewaygroup.
Thetablewillbeofflineafterapassphrasechange.
Youmustusethisoptiontore-encryptthedata.Youmustentertheold
APIGatewaypassphrasetoproceed.Dataisre-encryptedusingthe
currentAPIGatewaypassphrase.

Table Description
Administration
Re-create Recreateatable.Thisisusefulindevelopmentifyouwishtochange
thetablestructure.Thisprocedureinvolvesdroppingandrecreating
thetable,soallexistingdatawillbelost.Thestepsareasfollows:
1. Backup(optional).
Backupthedataifnecessaryusingkpsadmin.
2. Deploythecorrectconfiguration.
FirstredeploythecorrectconfigurationusingPolicyStudio.This
mayresultinsomeKPSdeploymenterrors.Thechangesyouhave
mademaynolongermatchthestoreddatastructure.
3. Re-createthetablewiththecorrectconfiguration.
SelecttheRe-createoptionusingkpsadmin.
4. Restore(optional)
Restorethedatausingkpsadmin.Ifyouhavemadekeyorindex
changes,thedatashouldimportdirectly.Ifyouhavemademore
extensivechanges(forexample,renamingfieldsorchanging
types),youmustupgradethedatatomatchthenewtable
structure.
TableDetails Displayinformationaboutatableanditsproperties.
Collection administration operations

Thekpsadminoperationsforcollectionadministrationareasfollows:
Collection Description
Administration
ClearAll Clearalldatainalltablesinthecollection.
BackupAll Backupalldatainalltablesinthecollection.
RestoreAll Restorealldatainalltablesinthecollection.
Re-encryptAll Re-encryptalldatainalltablesinthecollection.
CollectionDetails Displayinformationaboutalltablesinthecollection.

Cassandra administration operations

ThekpsadminoperationsforCassandraadministrationareasfollows:
Cassandra Description
Administration
ShowConfiguration ShowthecurrentconfigurationfortheKPS-embeddedstorageservice
(ApacheCassandra).
General administration operations

Thekpsadminoperationsforgeneraladministrationareasfollows:
General Description
ChangeTable Changethecurrentlyselectedtable.
ChangeCollection Changethecurrentlyselectedcollection,andselectatableinthat
collection.
ChangeGroupor Refreshtheconfiguration,andchangethecurrentlyselected
APIGateway APIGatewaygroupandKPSAdminAPIGateway.
DebugMode Enableordisabledebugmode.Toenable,youmustenterthe
APIGatewaygrouppassphrase.EncrypteddatainKPStablesisthen
shownintheclear.Thiscanbeusefulfordebuggingissuesonthe
APIGateway.
Example switching data source

ThisexampleshowshowtoswitchfromCassandrastoragetofilestorage.
Step 1: Backup collection data using

kpsadmin
Tocopythecurrentdatainthecollectiontothenewdatasource,backupthecollectiondatausing
kpsadminoption21)BackupAll.
ThebackupUUIDishighlightedinthefollowingexample:

Step 2: Create a new data source

Tocreatethenewdatasource,performthefollowingsteps:
1. InthePolicyStudiotree,selectKey Property Stores>Samples.
2. SelectthecollectionData Sourcestab.
3. ClickAdd>Add Fileatthebottomright.
4. EnterafiledatasourceNameandDescription.
5. EnteraDirectory Path(forexample,${VINSTDIR/kps/samples).

Tip Youcaninclude${VINSTDIR}or${VDISTDIR}toindicatetheAPIGatewayinstance
directoryorinstalldirectoryrespectively.Makesuretouse\onWindowsor/onUNIX.If
thedirectorydoesnotexist,itisautomaticallycreated.
6. SelectthecollectionPropertiestab.
7. ChangethecollectionDefault data sourcetousethenewdatasource:
Step 3: Deploy the configuration

ClicktheDeploybuttoninthePolicyStudiotoolbar.
Step 4: Restore collection data using

kpsadmin
Ifyoumadeabackupinstep1,torestorethecollectiondata,performthefollowingsteps:
1. Usingkpsadmin,selectoption22)RestoreAll.
2. EnterthebackupUUIDnotedinstep1.Forexample:

Configure Apache
Cassandra KPSstorage 6
ApacheCassandraprovidesahighlyavailable(HA)datastorageoptionforKPS.Bydefault,each
APIGatewayrunsanembeddedCassandraserver.YoumustconfiguretwoormoreAPIGatewaysto
provideaHAdataservice.
AsingleAPIGateway,non-HAsystemdoesnotrequireanyconfiguration.Foranoverviewofthis
configuration,seeSinglenode,out-of-the-box,non-HAconfigurationonpage37.
ThisguidedescribesusecasestestedwithAPIGateway.Forproductiondeployments,seethe
ApacheCassandraandDatastaxdocumentation.Youshouldensurethatyouarefamiliarwith
Cassandraconfigurationandadministrationrequirements.
Note nodetoolrepairmustberunatregularintervalstoensurethatdeleteddataremains
deletedinacluster.Forexampleusecases,seeApacheCassandraoperationsfor
APIGatewayonpage69.
Cassandra configuration
IntheAPIGateway,Cassandraconfigurationanddataarestoredinthefollowingdirectory:
INSTALL_DIR/groups/<group-id>/<instance-id>/conf/kps/cassandra
YoucanconfigureAPIGatewaytorunanembeddedCassandraserverandclient.TheCassandra
configurationisstoredasfollows:
File Description
cassandra.yaml Cassandraserverconfigurationfile.
client.yaml Cassandraclientconfigurationfile.
jvm.xml JMXconfigurationrequiredforCassandraadministration.
commitlog Cassandradatadirectory.
data Cassandradatadirectory.
saved_caches Cassandradatadirectory.

6 Configure Apache Cassandra KPSstorage
Cassandra ports
ThissectiondescribestheavailableportsintheCassandraconfigurationfiles:
cassandra.yaml
TheCassandraserverconfigurationfileincludesthefollowing:
Property Description Default
storage_port TCPportforserverservercommunication. 7000

Thesameportmustbeusedacrossthe
cluster.
listen_address TCPAddressforserverserver localhost

communication.Eachservermusthavea
uniqueaddress.
rpc_port TCPportforclientcommunication. 9160
rpc_address TCPaddressforclientcommunication. localhost
seed_provider/ Atleastoneseedmustbeavailablewhen localhost

parameters/seeds bootstrappinganewnodeforthefirsttime.
client.yaml
TheCassandraclientconfigurationfileincludesthefollowing:
hosts Comma-separatedlistofserveraddress:port localhost:9160

pairs.

jvm.xml
TheJMXconfigurationfileincludesthefollowing:
com.sun.management.jmxremote.port CassandraJMXmonitoringport. 7199

Aftertheinitialhandshake,the 1024+
JMXprotocolrequiresthatthe
clientreconnectsonarandomly
chosenport(1024+).
ToenableJMX,removethe
<if>clausefromthisfile.
Note Youmustensurethefollowing:
l conf/kps/cassandradirectoryisincludedaspartofyourAPIGatewaybackupplan.
Formoredetailsonbackup,seetheAPIGatewayAdministratorGuide.
l Changestocassandra.yaml,client.yaml,andjvm.xmlrequireanAPIGateway
restart.
l cassandra.yamlisuniquetoeachAPIGatewayinstancebecauseitcontainsaunique
listen_addressforeachAPIGateway.
Secure ports
Thefollowingfirewallrulesapplyforsecuringports:
l storage_port:listen_addressmustbeavailabletootherhostsinthecluster.
l rpc_port:rpc_addressandcom.sun.management.jmxremote.portcanberestrictedto
localaddresses.
l UseSSHtogettothemachinetorunCassandraclientandadministrationtoolssuchas
nodetoolandcassandra-cli.
Cassandra logging
CassandraloggingissettoERRORlevelbydefault.ToenableCassandradebugoutput,performthe
followingsteps:
1. Editthefollowingfile:
INSTALL_DIR/system/lib/log4j.properties
2. UpdateERRORtoDEBUGforlog4j.logger.org.apache.cassandra(server)and
me.prettyprint.cassandra(client).

3. RestartAPIGateway.
Cassandraconfiguration steps
ThemainCassandraconfigurationstepsareoutlinedasfollows:
1. ConfiguretheCassandratopologyincassandra.yaml,client.yaml,andjvm.xml.
2. StartAPIGatewayswithembeddedCassandraservers
3. ConfiguretheCassandrareplicationfactor
4. Configurerequestconsistencylevels
Step 1: Configure the Cassandra topology

YoumustdecideontheCassandratopology,replicationfactor,andconsistencylevelsforyour
application.Thissectiondescribesrecommendedandtestedtopologyconfigurationsin
cassandra.yaml,client.yaml,andjvm.xml.Indevelopment,youcanalwaysstartwithone
nodeandreconfigurelater.
Single node, out-of-the-box, non-HA configuration

Thisistheout-of-the-boxAPIGatewayconfiguration.Nofurtherconfigurationisrequired.
Thisconfigurationisdescribedasfollows:
l CassandraserverAistheseednode
l Serverservercommunicationonport7000(mustbethesameacrossthecluster)
l Clientsconnecttotheirlocalserver
l JMXisdisabled(notneededforsinglenodesystem)
l Consistentreadsandwrites
l NoHA
Thefollowingdiagramshowsanexampleconfiguration:

Note WhenaCassandraserverstartsupforthefirsttime,itcontactsaseednodetoobtain
informationaboutotherserversinthecluster.Inamulti-servercluster,atleastoneseed
nodemustbeavailablewhenstartingaCassandraserverforthefirsttime.
Multiple nodes, single host, out-of-the-box, non-HA

configuration
WhenrunningmultipleAPIGatewaysonthesamehost,thefirstAPIGatewaytorunactsasa
Cassandraserver.Subsequentserverstorunactasclients.Thisissufficientwhengettingstarted.
However,theCassandraserverdesignationdependsontherunorder.
Note OnAPIGatewaysthatshouldrunasCassandraclients,renameorremovethe
cassandra.yamlfile,andrestarttheseAPIGateways.Ifaclientstartsupbeforeaserver,
youwillgetmultipleerrorssuchas:
me.prettyprint.hector.api.exceptions.HectorException:Allhostpoolsmarked
down.Retryburdenpushedouttoclient
However,thisisexpected.TheclientwillnotbeabletofieldCassandrarequestsuntilaserveris
available.

Note Thisisaclientserverconfiguration.IftheserverAPIGatewayisnotavailable,KPSdata
andfunctionalitywillnotbeavailabletoclientAPIGateways.Ifyouwanthigheravailability
withCassandra,configureasuitableHAconfigurationasdescribedinthefollowing
sections.
Multiple node prerequisite: IP address required per Cassandra server

FortrueHA,youshoulduseseparatehosts.However,fordevelopment,youcansetupatestIP
address.Forexample,youcanconfiguremultipleIPaddressesonasinglehostasfollows:
Windows
Editorcreatethefollowingfile:
C:\Windows\System32\drivers\etc\hosts
Addthefollowinglines:
127.0.0.1127.0.0.N
Linux

Enterthefollowingcommand:
sudoifconfiglo:N127.0.0.Nnetmask
255.0.0.0up
WhereNis2,3,4.
Thefollowingexampleshowsifconfigo utputonLinux:
Two-node HA eventual consistency

Thisisatwo-APIGatewaysystem,withIPaddressesipAandipB.NotetheMultiplenode
prerequisite:IPaddressrequiredperCassandraserveronpage39.Thisconfigurationisdescribedas
follows:
l TwoCassandraserversAandBdefinedinacluster(serverAistheseednode)
l Serverservercommunicationonport7000.Thismustbethesameacrossthecluster
l JMXisenabledforadministration
TheCassandraparameterconfigurationincludesthefollowing:
l EventualConsistency:Read=Write=ONE
l Replicationfactor:2
l Cansurvivethelossofonenode
l Eachnodeholds100%ofthedata

Three-node HA full consistency

Thisisathree-APIGatewaysystem,withIPaddressesipA,ipB,andipC.NotetheMultiplenode
prerequisite:IPaddressrequiredperCassandraserveronpage39.Thefollowingdiagramshowsan
exampleconfiguration:

Thisconfigurationisdescribedasfollows:
l ThreeserversA,B,andCdefinedinacluster(serverAistheseednode)
l Serverservercommunicationonport7000(mustbethesameacrossthecluster)
l JMXenabledforadministration
TheCassandraparameterconfigurationincludesthefollowing:
l Consistent:Read=Write=QUORUM
l Replicationfactor:3
l Cansurvivethelossofonenode
l Eachnodeholds100%ofthedata
Two-node HA eventual consistency, with additional

client-only node
Thisissimilartotheprevioustwonodesystemswithanadditionalclient-onlynode.Forexample,
youwouldchoosethisoptionforthefollowingreasons:
l Thereareresourceusageissuesorrestrictionsoncertainserversinthecluster(forexample,disk,
memory,CPU,JARs,classpath,andports)
l Youdonotwanttostoredataatrestoncertainservers
l Youwanttoseparatethedatalayerfromtheapplicationlayer

Note IfeitherCassandraservergoesdown,theclientautomaticallyfailsovertotheotherserver.
Step 2: Start APIGateways with embedded

Cassandra servers
Onfirsttimerun,performthefollowingsteps:
1. Ensurethattheseednodeisstartedfirst.Waitforthisnodetostart.
2. Startupothernodesinturn.Waitforeachnodetostart.
Tip Youcanverifytheconfigurationbyrunning./kpsadminandselectingOption30)
Showconfiguration.
Step 3: Configure the Cassandra replication

factor
Toconfigurethereplicationfactor,performthefollowingsteps:
1. Runcassandra-cliinanAPIGatewaybindirectory.
2. Executethefollowingcommands:

./cassandra-cli-h127.0.0.2
usekps;
updatekeyspacekpswithstrategy_
options={replication_factor:2};
quit;
Inthisexample,thereplicationfactoris2.EnterthecorrectreplicationfactorforyourCassandra
topology.Formoredetails,seeStep1:ConfiguretheCassandratopologyonpage37.
3. Synchroniseandverifythischangeacrosstheclusterbyexecutingnodetoolrepairagainst
eachnode.Inthefollowingexample,nodetoolisexecutedagainstatwo-nodecluster
runningonIPaddressesof127.0.0.1and127.0.0.2:
./nodetool-h127.0.0.2repairkps
./nodetool-h127.0.0.3repairkps
./nodetool-h127.0.0.2ringkps
Youshouldseeaneffectiveownershiponeachnodeof100%.Forexample:
Note Cassandra1.2.18nodetoolrequiresthelocationofcassandra.yaml.Youmustupdate
apigateway/system/conf/cassandra-tools-jvm.xmltospecifylocationof
cassandra.yaml.Donotuse$VINSTDIRbecausethesystemdoesnotknowwhich
APIGatewaytoresolveto.Forexample:
<ConfigurationFragment>

<PathAddname="PATH"value="$VDISTDIR/win32/jre/bin/server"/>
<JVMSettings>
<ClassDirname="$VDISTDIR/system/lib/modules"/>
<ClassDirname="$VDISTDIR/system/lib/modules/cassandra/server"/>
<SystemPropertyname="cassandra.config"
value="file://$VDISTDIR/groups/group-2/instance-
1/conf/kps/cassandra/cassandra.yaml"/>
</JVMSettings>
</ConfigurationFragment>

Step 4: Configure request consistency levels

InPolicyStudio,settherequestconsistencylevelsspecifiedinyourCassandratopology.Formore
details,seeStep1:ConfiguretheCassandratopologyonpage37.
Toconfigurerequestconsistencylevels,performthefollowingsteps:
1. SelectaKPScollectioninPolicyStudio(forexample, Key Property Stores>Samples).

2. SelecttheData Sourcestab.
3. SelecttheDefault Embedded Data Source,andclickEditatthebottom.
4. Inthedialog,selecttheappropriateRead Consistency LevelandRead Consistency Level
valuesforyourtopology.
5. ClickDeployinthePolicyStudiotoolbar.
ThefollowingexampleshowssCassandraconsistencylevelsettooneforreadandwritefora
collectioncalledSamples:
Disable Cassandra storage

IfyoudonotwanttouseCassandrastorage,andyouarenotusingCassandraforOAuthtoken
storage,youcandisableCassandrastorage.
TodisableCassandrastorage,performthefollowingsteps:
1. RunthefollowingsamplescriptagainsttheAPIGateway.Thisupdatesthe APIGateway
configurationbyswitchinganyCassandrausagetofileusage.
Windows
cdINSTALL_DIR\samples\scripts

run.batcassandra/disableCassandra.py
UNIX
cdINSTALL_DIR/samples/scripts
./run.shcassandra/disableCassandra.py
2. RestarttheAPIGateway.
3. IfyouarerunningmultipleAPIGatewaysinthegroup,deploytheupdatedconfigurationto
theseAPIGatewaysandrestartthem.

Configure database
KPSstorage 7
KPSdatacanbestoredinarelationaldatabase.APIGatewaysupportsthefollowingdatabases:
l Oracle
l IBMDB2
l MicrosoftSQLServer
l MySQL
Theoptionsfordatabasestorageareasfollows:
l Shared database storage:DataformultipleKPStablesisstoredinasinglededicated

databasetable.DataisencodedinJSONbeforebeingstored.Thisapproachisveryflexible
becauseitallowsmapsandliststobestoredintables.Italsominimizesadministrationoverhead
becauseonlyasingledatabasetableneedstobecreatedandmanaged.Thisisthe
recommendedapproach.Formoredetails,seeShareddatabasestorageonpage47.
l Per-table database storageEachKPStableisbackedbyasingledatabasetable.Each
propertyintheKPStablemapstoacorrespondingcolumninthedatabasetable.Thisapproach
allowsexistingtablestobereused,andallowsmoreprecisetuningatdatabaselevel.However,
italsohassignificantlimitations(forexample,supporteddatatypes,andaddingandviewing
data).Formoredetails,seePer-tabledatabasestorageonpage51.
Shared database storage

Forshareddatabasestorage,asingledatabasetableisusedtostoredataformultipleKPStables.
Thissectiondescribesthestorageconfigurationsteps.
Step 1: Create a KPS database table

Createadatabasetablecalledkps_objectbyexecutingtheappropriateSQLscriptforyour
databasesystem.SQLscriptsareavailableinthefollowinglocation:
INSTALL_DIR/system/conf/sql/DB_NAME/kps.sql
Note ForOracle,ensurethatthedatabaseiscreatedwiththeAL32UTF8charactersetencoding
tosupportUTF8.

7 Configure database KPSstorage
Step 2: Set up an external connection to the

database
ToaccessthistablefromtheAPIGateway,youmustsetupanexternaldatabaseconnectionfrom
theAPIGateway.Formoredetails,seetheAPIGatewayPolicyDeveloperGuide.
ThefollowingshowsexampledatabaseconnectionsettingsinPolicyStudio:
Note ForMySQL,thetablecreationscriptspecifiesUTF8.YoumustalsousethecorrectJDBC
connectionURL.UpdatetheconnectionURLfieldtospecifyunicode&UTF8.For
example:
jdbc:mysql://testserver:3306/kps?useUnicode=true&characterEncoding=UTF-8
Step 3: Use the external connection in a KPS

collection
WhencreatingaKPScollection,youcanselectdatabasestorageintheDefault datasourcefield.
ThefollowingexampleshowsanSQLdatabaseselected:

Alternatively,youcanaddadatabasestorageoptiontothecollectionlater.Onthe Data Sources

tab,selectAdd>Add Database.Foranexample,seeStep2:Addthedatabasedatasourcetothe
KPScollectiononpage52.
Foranexamplewithfilestorage,seeConfigurefile-basedKPSstorageonpage59.
Database storage information

ThefollowingdescribeshowKPSdataisstoredinadatabase:
l ThemaximumprimarykeylengthinaKPSrowis255characters
l ThemaximumKPStablenamelengthis255characters
l KPSrowsareJSONencoded
l Optimisticlockingisusedandisenforcedusingaversioncolumn
Increase row size

YoucanincreasethemaximumKPSrowsizebychangingthelargeValuecolumn.Forexample,to
supportimageiconsinMySQL,enterthefollowingcommand:
altertablekps_objectmodifycolumnlargevaluemediumtext;
Logging for shared table storage

ShareddatabasestorageusesApacheOpenJPAtohandlethecommunicationbetweenKPSandthe
back-enddatabase.YoucanuseOpenJPAloggingtoviewtheSQLrequeststransmittedtothe
databaseandtheirresponses.Thisinformationcanbeusefulfordebugging.Youcanconfigure
OpenJPAloggingusingApachelog4jproperties.

Enable OpenJPA debug logging

ToenableOpenJPAdebuglogging:
INSTALL_DIR/apigateway/system/lib/log4j.properties
2. Addthefollowingsettings:
log4j.rootLogger=DEBUG,A1,Vordel
#OpenJPA
log4j.category.openjpa.Tool=DEBUG
log4j.category.openjpa.Runtime=DEBUG
log4j.category.openjpa.Remote=DEBUG
log4j.category.openjpa.DataCache=DEBUG
log4j.category.openjpa.MetaData=DEBUG
log4j.category.openjpa.Enhance=DEBUG
log4j.category.openjpa.Query=DEBUG
log4j.category.openjpa.jdbc.SQL=DEBUG
log4j.category.openjpa.jdbc.SQLDiag=DEBUG
log4j.category.openjpa.jdbc.JDBC=DEBUG
log4j.category.openjpa.jdbc.Schema=DEBUG
4. Verifythatdebugstatementsarewrittentothelog.
Disable OpenJPA debug logging

TodisableOpenJPAdebuglogging:
INSTALL_DIR/apigateway/system/lib/log4j.properties
2. SubstituteERRORforDEBUGinthelog4j.category.openjpasettings.
4. Verifythatnodebugstatementsareprintedtothelog.
FormoreinformationonApacheOpenJPAlogging,see:
http://openjpa.apache.org/builds/2.2.2/apache-openjpa/docs/main.html

Per-table database storage

YoucanusethisoptiontomapaKPStabletoasingledatabasetable.Thestructureofbothtables
mustmatch,soanewdatabasetableisrequiredforeachnewKPStable.WhentheKPStableis
queried,anSQLstatementisexecutedtoretrievethecorrectrowfromtheunderlyingdatabase
table.ThisSQLstatementisprovidedbytheuserinPolicyStudio.
However,tablesthatuseper-tabledatabasestoragehavesignificantlimitations:
l DatacannotbeaddedthroughKPS,butonlydirectlythroughthedatabase
l DatacannotbeviewedinkpsadminorAPIGatewayManager,butcanonlybereadbyselectors
atruntime
l Tablescanonlycontainsimpledatatypes,notmapsorlists
KPStablescanbequeriedusingsimpleorcompositekeys.Thissectionshowsexamplesofboth.
Map a database table using a single key

Inthisexample,aKPStableisaccessedusingasinglekeyproperty.Thiskeyisusedtoretrievethe
correctrowfromthedatabasetable.ThisexampleusesthefollowingUsertableanddatacreated
usingaMySQLclient:
CREATETABLEUser(
emailVARCHAR(100),
passwordVARCHAR(100),
firstNameVARCHAR(100),
lastNameVARCHAR(100),
ageINT
);
insertintoUser(email,password,firstName,lastName,age)values
("ralph.jones@acme.com","password","Ralph","Jones",30);
insertintoUser(email,password,firstName,lastName,age)values
("kathy.adams@acme.com","blah","Kathy","Adams",35);
Step 1: Set up an external connection to the

database
ToaccessadatabasefromtheAPIGateway,youmustsetupanexternaldatabaseconnection(see
Step2:Setupanexternalconnectiontothedatabaseonpage48).Thisexampleusesthe
configurationfromGetstartedwithKPSonpage10.

Step 2: Add the database data source to the

KPScollection
Toaddadatabasedatasource,performthefollowingsteps:
1. OntheKPScollection Data Sourcestab,selectAdd>Add Database.
2. SpecifytheDatabase Connectioninthedialog(forexample,TestDBConnection):
Step 3: Map the SQL table to a KPStable

FromanexistingKPScollection,performthefollowingsteps:
1. Right-clicktheKPScollection,andselectMap SQL Table:

2. Enteranaliasinthedialog(forexamplemapUser):
3. Enteradatabase-specificJDBCSQLquerytoretrievetherequireddata.Forexample:
select*fromUserwhereemail=?
4. OnthePropertiestabofthenewKPStable,selectthenewdatabasedatasourceinOverride
the default data source with the following:

Step 4: Define the KPS table structure

YoumustdefineaKPStablestructureintowhichdatawillberead.Youmustspecifythefieldsthat
youexpecttoreadwiththeSQLquery.Inthisexample,allfieldsinthetablearereadusingan
asterisk(*)intheSQLquery.Thislistsallfields,sotheorderdoesnotmatterinthiscase.However,
thenamesandtypemustmatchtheresultreturnedbytheSQLquery.
InthisSQLquery,emailistheprimarykey.Youspecifyemailasthepropertytousein
correspondingselectorqueries:
Forexample,youcanusethefollowingselector:
${kps.mapUser
["kathy.adams@acme.com"].age}
Note ThissyntaxusesASCIIquotationmarks(").
ThisselectorgeneratesthefollowingSQLquery:
select*fromUserwhereemail=
"kathy.adams@acme.com"

Step 5: Define the policy and path

YoucanreusethepolicyandpathfromGetstartedwithKPSonpage10withonechangeusethe
mapUserKPSaliasforthisnewtable.Forexample:
Step 6: Deploy and run

ClickDeployinthePolicyStudiotoolbar.
Torunthepolicyinyourbrowser,goto:
http://localhost:8080/kpsGetViaSelector?id=kathy.adams@acme.com
ThisURLspecifiestheuserID(email)askathy.adams@acme.com.
Forexample,theresultisasfollows:

How to map a database table using a

composite key
ThissectionmodifiestheexampleinMapadatabasetableusingasinglekeyonpage51.This
sectionshowshowatablewithacompositesecondarykeycanbeaccessedfromaselector.Inthis
version,thesecondarykeyis{firstName,lastName}.
Step 1: Modify the KPS table

Youmustupdatethedatabase-specificJDBCSQLqueryintheKPStabletoretrievetherequired
data.
TomodifytheKPStable,performthefollowingsteps:
1. OnthePropertiestabintheQueryfield,enterthefollowing:
select*fromUserwherefirstName=
?andlastName=?
Forexample:
2. Onthe Structuretab,changetheselectorpropertiestofirstName,lastName:

Step 2: Modify the policy

Youmustupdatethe Set MessagefilterinyourpolicytousefirstNameandlastName
parameters.Forexample:
EnterthefollowingintheMessage Bodyfield,usingasinglelineforeachentry(Email,First
Name,LastName,andAge):
========================
User
===
Email:${kps.mapUser[http.querystring.firstName]
[http.querystring.lastName].email}

FirstName:${kps.mapUser[http.querystring.firstName]
[http.querystring.lastName].firstName}
LastName:${kps.mapUser[http.querystring.firstName]
[http.querystring.lastName].lastName}
Age:${kps.mapUser[http.querystring.firstName]
[http.querystring.lastName].age}
========================
Step 3: Deploy and run

ClickDeployinthePolicyStudiotoolbar.
Torunthepolicyinabrowser,gotothefollowingURL:
http://localhost:8080/kpsGetViaSelector?firstName=Kathy&lastName=Adams
Forexample,theresultisasfollows:

Configure file-based KPS
storage 8
YoucanstoreKPSdatainadirectoryonthefilesystem.EachtableisstoredinasingleJSONfile.
File-basedstorageisspecifiedattheKPScollectionorKPStablelevel.
Note File-basedKPSstorageismostsuitedtosingleAPIGatewaydeployments.Inamulti-
APIGatewayscenario,filereplicationorashareddiskisrequiredtoensurethatall
APIGatewaysusethesamedata.
File-basedKPStablesarereadandcachedbyAPIGatewayswhentheystartup.Ifdataismodified,
allAPIGatewaysmustberestartedtopickupthechanges.
Configure a file-based KPS collection

Youcanconfigureafile-basedKPSdatasourcewhencreatingaKPScollection,oraddonelateron
theData Sourcetab.Forexample,thefollowingsettingsareavailablewheneditingfile-based
collection:
Thesesettingsaredescribedasfollows:
Name Description
Name Collection-uniquedatasourcename.
Description Optionaldescription.
Directory Thedirectorynamewheretabledataforthecollectionisstored.Ifthe
Path directorydoesnotexist,itisautomaticallycreated.Ifthisdirectoryisnot
specified,thedirectorypathdefaultsto${VINSTDIR}/conf/kps.
ThepathcanincludeVDISTDIRorVINSTDIRvariables.Theseareresolvedto
theAPIGatewayinstanceandinstallationdirectories.Forexample,
${VDISTDIR}/mydata/samples.Remembertousethecorrectpath
separator(/onUNIXand\onWindows).

Appendix A: KPS FAQ
ThisappendixanswersthefrequentlyaskedquestionsonKPSandAPIGateway,KPSstorage,and
ApacheCassandra.
KPS and APIGateway

ThissectionincludesfrequentlyaskedquestionsonKPSandAPIGateway:
What is KPS used for in APIGateway?

InadditiontouseinyourAPIGatewaypolicies,KPSisusedasanoptionforOAuthtokenstorage,
andClientApplicationRegistry.Ifyoudonotwishtousethesefeatures,ordonotwishtousethe
embeddedApacheCassandraserviceasastoragemechanismforthesefeatures,seeConfigure
ApacheCassandraKPSstorageonpage34fordetailsonhowtodisableCassandrastorage.
What is KPS not suitable for?

KPSisnotsuitableforcomplicateddatamodels,adhocqueries,orwherefullACIDtransaction
supportisrequired.KPSdoesnotenforcereferentialintegrity.
What are the transaction semantics of KPS?

IndividualKPSoperationsareatomic(A),isolated(I),anddurable(D).Consistency(C)dependson
thedatastoragemechanismchosenandthenumberofAPIGatewaysinagroup.
Withfilestorage,dataisconsistentinasingleAPIGateway.Withsupporteddatabasestorage,data
isconsistent.CassandrastorageallowsconsistencylevelstobesetperKPStable.KPSdoesnot
providetransactionsacrossmultipleoperations.YoucannotissueasetofKPSoperationsandroll
themback.
What is the KPS collection alias prefix for?

ThisprovidesanoptionalnamespaceforaKPScollectiontohelpensurethattablesinthecollection
haveauniquealias.Inmostcases,youcanleavethisprefixempty.

Appendix A: KPS FAQ
Why are some collections hidden? How can

you show them?
Someout-of-the-boxKPScollectionsarehiddeninPolicyStudiotopreventaccidentalmodification.
ToshowhiddenKPScollections,performthefollowingsteps:
INSTALL_DIR/policy_studio/policystudio.ini
2. Settheshow.internal.kps.collectionsystempropertytotrue.Forexample:
3. RestartPolicyStudio.
Note YouwillneedtoeditthesehiddencollectionsifyouwishtochangeCassandraconsistency
levels(forexample,whenswitchingtoanHAsetup).
How do I change APIGateway group

passphrase?
Tochangethegrouppassphrase,performthefollowingsteps:
1. ChangethegrouppassphraseinPolicyStudio.Fordetails,seetheAPIGatewayAdministrator
Guide.
2. Inkpsadmin,selecttheCollectionAdministration,Re-encryptAlloptiontore-
encryptthedataineachcollection.
3. YouwillbeaskedtoentertheoldAPIGatewaypassphrase.Thispassphraseisusedtodecrypt
thedata.Thedataisthenre-encryptedwiththecurrentAPIGatewaypassphrase.
Formoredetails,seeManageaKPSusingkpsadminonpage28.

Appendix A: KPS FAQ
KPS storage options

ThissectionincludesfrequentlyaskedquestionsonKPSstoragemechanisms:
Is Apache Cassandra storage required? Can

you use file or database?
ApacheCassandraisthedefaultout-of-the-boxstorage,butisnotarequirement.Youcanswitchto
fileordatabasestorage.Formoredetails,seeHowdoyouswitchstorageforaKPScollection?on
page62.
How do you switch storage for a KPS

collection?
ThegeneralstepstoswitchstorageforaKPScollectionareasfollows:
1. Backupthedataforacollectionusingkpsadmin.
2. Addandconfigureanewdatasource(file,database,orCassandra)usingPolicyStudio.
3. DeploytheconfigurationinPolicyStudio.
4. Restorethedatausingkpsadmin.
Formoredetails,seetheexampleinManageaKPSusingkpsadminonpage28.
Why use database storage?

Youmayalreadyhavearelationaldatabasesystemandexpertisethatyouwishtouse.Formore
details,seeConfiguredatabaseKPSstorageonpage47.
Why use file storage?

Filestorageisveryeasytouse.DataiswrittentoverysimpleJSONencodedfiles.Filestorageis
suitableforsingleAPIGatewayuseindevelopmentandproduction.Ifyouhavemorethanone
APIGatewaysharingthefiles,youmustrestarttheseAPIGatewaysafteraKPSupdate.Itisonly
suitablehereforrarelychanging,read-mostlydata.Formoredetails,seeConfigurefile-basedKPS
storageonpage59.

Appendix A: KPS FAQ
When can you use kpsadmin? When should

you use storage-specific tools?
Youcanusekpsadminanytime.However,itisespeciallyusefulfordevelopmentuse.In
production,youshouldusestorage-specifictoolsandprocedures(forexample,fordatabackup).
Formoredetailsonkpsadmin,seeManageaKPSusingkpsadminonpage28.
Apache Cassandra
ThissectionincludesfrequentlyaskedquestionsontheApacheCassandradatabase:
Why use Cassandra as a KPS storage

option?
Cassandraisakey-valuestore.Cassandrahasanon-restrictiveApache2.0license.ItprovidesHA,is
embeddableinaJavaapplication(APIGateway),andhasanactivecommunity.
What version of Cassandra does the

APIGateway use?
TheAPIGatewayshipswithaversionofCassandra1.2.18.Non-requiredJARsandscriptshavebeen
removed.Thecassandra-cliandnodetoolutilitiesareincluded.
What does all host polls marked down

mean?
ThismeansthattheembeddedclientcannotconnecttotheembeddedCassandraserver.Fordetails
onhowtoresolvethisissue,seeTroubleshootKPSerrormessagesonpage65.
Can you use an external Cassandra

instance?
Youcanmodifytheclient.yamlfileinAPIGatewayCassandraconfigurationtopointtoan
externalCassandrainstance.ThiswillreduceresourceusagerequirementsintheAPIGateway
process.

Appendix A: KPS FAQ
How do you set Cassandra consistency

levels?
Fordetails,seeConfigureApacheCassandraKPSstorageonpage34.
How do you disable Cassandra?

Fordetails,seeConfigureApacheCassandraKPSstorageonpage34.

Appendix B: Troubleshoot KPS
error messages
ThisappendixdescribesvariousKPSerrormessages,andexplainshowtoresolvethem.
All platforms
ThissectionexplainshowtotroubleshootKPSerrorsonallplatforms:
All host polls marked down

ThiserrormeansthattheembeddedclientcannotconnecttotheembeddedCassandraserver.
Toresolvethisissue,performthefollowingsteps:
l Checkthatallportsandaddressesarecorrectincassandra.yamltoverifythattheendpoints
arewhatyouexpect.
l Runkpsdamin,andselectCassandraAdministration,ShowConfigurationtoreadthis
configuration.Andverifytheresultiswhatyouexpect.Formoredetails,seeManageaKPSusing
kpsadminonpage28.
l EnableCassandradebuglogging.
FormoredetailsonCassandraconfigurationandlogging,seeConfigureApacheCassandra
KPSstorageonpage34.
Nodetool reports failed to connect

WhenrunningthenodetoolcommandagainstaremotehostintheCassandracluster,the
followingerrorisoutput:
Failedtoconnectto'REMOTE_IP:7199:Connectionrefused'
1. Oneachnode,editthejvm.xmlfileinthefollowingdirectory:
INSTALL_DIR/apigateway/groups/GROUP_ID/INSTANCE_ID/conf/kps/cassandra
2. AddthefollowingJVMargument:
java.rmi.server.hostname=BIND_ADDRESS

Appendix B: Troubleshoot KPS error messages
FormoredetailsonCassandraconfiguration,seeConfigureApacheCassandraKPSstorageonpage
34.
May not be enough replicas present to

handle consistency level
Forexample,thiserrorisreceivedinatwo-nodeCassandrasystemwithaneventualconsistencyof
read=write=ONE.
Toresolvethisissue,youmustensurethatthereplicationiscorrectly.Forexample,youcanusethe
followingnodetoolcommand:
Datacenter:datacenter1
==========
Replicas:1xxxxx
AddressRackStatusState
LoadOwnsToken7564491331177403445
127.0.0.2rack1UpNormal1.19MB35.10%-
1090016113642762867
127.0.0.3rack1UpNormal2.17MB64.90%-
7564491331177403445
Note Inthiscase,thenumberofreplicasis1andOwnsisnot100%pernode.Youshouldset
thereplicationfactor,synchronizethechanges,andverifyasdescribedinConfigure
ApacheCassandraKPSstorageonpage34
Windows only
ThissectionexplainshowtotroubleshootKPSerrorsonWindowsonly:
Node running in client mode

OnWindows,thesoftwaredetectsthataserviceisalreadyrunningonthelocalmachine,even
thoughthereisonlyoneAPIGatewayrunning.
1. Editcassandra.yamlandclient.yaml.
2. ChangelocalhosttoIPnameoraddress.
3. RestartAPIGateway.
34.

UTF-8 characters not displaying correctly in

kpsadmin
ThisisaknownlimitationoftheWindowscommandconsole.ToviewUTF-8datacorrectly,run
kpsadmininaCygwinconsoleinstead.Formoredetailsonkpsadmin,seeManageaKPSusing
kpsadminonpage28.
FSUTIL utility bug

OnWindows,thefollowingerrormayoccur:
TheFSUTILutilityrequiresalocalNTFSvolume.at
org.apache.cassandra.utils.FBUtilities.exec(FBUtilities.java:573)
ThisisanWindowsXPissue,whichalsoappliestoNTFS(notjustFATxx).Formoredetails,see:
http://support.microsoft.com/kb/322275
Path length issue >255 characters

OnWindows,youmayseeanerrorsuchasthefollowing:
java.io.IOException:Exceptionwhileexecutingthecommand:cmd/c
mklink...
commanderrorCode:1,commandoutput:Thesystemcannotfindthepath
specified.
1. UseashortpathforCassandradata.
2. Updatethecassandra.yamldatadirectories:
data_file_directories:[dir-x]
commitlog_directory:dir-x
saved_caches_directory:dir-x
34.

Could not drop kps keyspace using

cassandra-cli
OnWindows,youmayseethiserrorwhichiscausedbyApachethrift.
Toresolvethisissue,youshoulddropindividualcolumnfamiliesandthekps_schemarecord.For
example,forasamples_usertable,pastethefollowingintocassandra-cli:
usekps;
assumekps_schemavalidatorasutf8;
assumekps_schemacomparatorasutf8;
assumekps_schemakeysasutf8;
assumesamples_uservalidatorasutf8;
assumesamples_usercomparatorasutf8;
assumesamples_userkeysasutf8;
dropcolumnfamilysamples_user;
delkps_schema['samples_user'];
Note Theassumecommandsmustbeexecutedonce.

Appendix C: Apache Cassandra
operations for APIGateway
ThisappendixdescribesimportantApacheCassandraoperationsfornoderepair,andbackupand
recovery.
nodetool repair
ThenodetoolrepaircommandrepairsinconsistenciesacrossallCassandrareplicasforagiven
rangeofdata.Formoredetails,see:
http://www.datastax.com/documentation/cassandra/1.2/cassandra/operations/ops_repair_
nodes_c.html
Youshouldexecutethiscommandweekly,atoff-peaktimes,andstaggerexecutionondifferent
nodes.
Thefollowingisasimplecrontabcommandthatexecutesrepairevery10minutes:
vagrant@node-3:~$crontab
*/10****/home/vagrant/from/apigateway/posix/bin/nodetool-hnode-3
repairkps>>/home/vagrant/nodetool.log
Note Thisisasimpleexamplefromadevelopmenttest.Inproduction,donotexecuterepair
every10minutes.
Backup and recovery

ThissectionexplainshowtobackupandrestoreallKPSdata.
Back up and restore Cassandra node data

TobackupandrestoreCassandradata(onlineandHA),usethefollowinginstructions:
http://www.datastax.com/documentation/cassandra/1.2/cassandra/operations/ops_backup_
restore_c.html
Note Whenrestoringfromasnapshot,youshouldfollowthenoderestartmethod.

Appendix C: Apache Cassandra operations for APIGateway
Back up APIGateway KPS configuration

KPSconfigurationisstoredinAPIGatewaythegroupconfigurationinthefollowingdirectory:
INSTALL_DIR/apigateway/group-n/conf
Youshouldregularlybackupthisdirectory.
Back up APIGateway Cassandra

configuration and data
APIGatewaygroupconfigurationanddataisstoredinthefollowingdirectory:
INSTALL_DIR/apigateway/group-n/instance-m/conf/kps/cassandra
ThiscontainstheCassandraconfiguration(cassandra.yaml,client.yaml,andjvm.xmlfiles).
ItalsoincludestheCassandraruntimedatainthedata,saved_caches,andcommitlog
subdirectories.
Youshouldregularlybackupthisdirectory.
Note FormoredetailsonAPIGatewaybackupanddisasterrecovery,seetheAPIGateway
AdministratorGuide.
Replace dead node

TheprocedureforastandardCassandrainstallationisasfollows:
http://www.datastax.com/documentation/cassandra/1.2/cassandra/operations/ops_replace_
node_t.html
TheprocedureforAPIGatewayisasfollows:
1. Confirmthatthenodeisdeadusingnodetoolstatus(seetheCassandraprocedureabove).
2. Notetheaddressofthedeadnode(thisisusedinthelaststep).
3. InstallanewAPIGateway,orrestoreabackupofanexistingAPIGateway.Donotstartthe
APIGateway.
4. TheAPIGatewayCassandradirectoryis:
INSTALL_DIR/apigateway/group-n/instance-m/conf/kps/cassandra
Copycassandra.yaml,client.yamlandjvm.xmlfromabackuporrecreateinthe
APIGatewayCassandradirectory.

Appendix C: Apache Cassandra operations for APIGateway
5. Backupandremovethedata,saved_caches,andcommitlogd irectoriesiftheyexist.
cassandra-topology.propertiesisrequiredformulti-datacentreconfiguration.Oracle
currentlydonottestorsupportthiskindofconfiguration.Formoredetailsonthe
cassandra.yamlfile,seethestandardCassandraprocedureabove.
Note auto_bootstrapshouldnotbelistedorshouldbesettofalse
6. StarttheAPIGatewaywiththe-Dcassandra.replace_addressoption.EnsureJMXis
enabled.Forexample:
./startinstance
-gTeamA
-napi2
-Dcassandra.replace_address=192.168.99.12
-DenableJMX
7. Remembertoremovethe-Dcassandra.replace_addressoptionforsubsequentstarts.


Further information

ThistopicshowswheretofindmoredetailsonKPS-relatedinformation:
Feature Documentation
KPS REST TheKPSRESTAPIisdocumentedinthefollowingdirectory:

API INSTALL_
DIR/apigateway/docs/restapi/APIGatewayAPI/api/rest/kps.htm
l
Apache FordetailsonCassandraversion1.2.x,seethefollowing:
Cassandra
l http://cassandra.apache.org/
l http://www.datastax.com/documentation/cassandra/1.2
Apache FordetailsonCassandraparameterconfiguration,seethefollowing:
Cassandra http://www.ecyrd.com/cassandracalculator/
parameter
configuration
API Gateway Fordetailsonhowtoconfiguredatabaseconnections,seetheAPIGateway

database PolicyDeveloperGuide.
connections
API Gateway Fordetailsonhowtoconfigurelocalcaches,seetheAPIGatewayPolicy

caches DeveloperGuide.

Glossary

Apache Cassandra
Anopensourcedistributeddatabase,designedtoprovidehighavailabilitybydistributingdata
acrossmultipleservers.
KPS
KeyPropertyStore.DatamanagementcomponentintheAPIGateway.
KPS alias
AnalternativenameforaKPStablethatisuniqueinanAPIGatewaygroup.
KPS collection
AcollectionofrelatedKPStables.
KPS table
AuserdefinedtablethatismanagedbytheKPSintheAPIGateway.
Selector
AspecialsyntaxthatenablesAPIGatewayconfigurationsettingstobeevaluatedandexpanded
atruntimebasedonmetadatavalues(forexample,fromaKPS,messageattribute,or
environmentvariable).

OAG KeyPropertiesStore

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

OAG KeyPropertiesStore

Загружено:

Авторское право:

Доступные форматы

Oracle Fusion Middleware

2 Get started with KPS 10

3 Configure KPS in Policy Studio 20

4 Access KPS data using selectors 26

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide3

6 Configure Apache Cassandra KPS storage 34

7 Configure database KPS storage 47

8 Configure file-based KPS storage 59

Appendix A: KPS FAQ 60

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide4

Appendix B: Troubleshoot KPS error messages 65

Appendix C: Apache Cassandra operations for API Gateway 69

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide5

Who should read this document

How to use this document

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide6

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide7

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide8

KPS data stores

KPS client applications

When to use a KPS

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide9

Column Type Description

age java.lang.Integer Userage.

email java.lang.String Useremailaddress.ThisisselectedinPolicyStudioasa

firstName java.lang.String Userfirstname.

lastName java.lang.String Usersurname.

password java.lang.String Userpassword,whichisselectedasEncryptedin

ExampletabledataisdisplayedontheSettings>Key Property StorestabintheAPIGateway

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide10

Before you begin

Define KPS configuration with Policy

Step 1: Define where data will be stored

1. InthePolicyStudiotree,sselectKey Property Stores,andselectAdd KPS Collection.

2. IntheAdd KPS Collectiondialog,namethecollectionSamples.

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide11

3. SelectaDefault data sourceofEmbedded (Cassandra)foralltablesinthecollection.

Step 2: Define the KPS table

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide12

5. Repeattoaddthefollowingcolumnsforyourtablestructureinthe Add Propertydialog:

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide13

Step 3: Define a policy that accesses the

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide14

Selector part Description

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide15

Selector part Description

Note AddaReflect Messagefilter(Conversioncategory)toreturnasuccessfulHTTP

Step 4: Deploy the configuration

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide16

Add KPS data using API Gateway Manager

4. Toenternewrecords,selectActions >New Entry:

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide17

Access KPS data from a policy

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide18

Enable APIGateway tracing

1. Inthetreeontheleft,selectServer Settings> General.

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide19

Configure a KPS collection

1. Right-clickKey Property StoresinthePolicyStudiotree,andselectAdd Key Property

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide20

Configure a KPS table

Oracle API Gateway11.1.2.4.0 Key Property Store User Guide21

KPS data sources