SDK Code Examples Version 2.4.2

Transcription

1 Version 2.4.2

2 This edition of SDK Code Examples refers to version of. This document created or updated on February 27, Please send your comments and suggestions to: Black Duck Software, Incorporated 8 New England Executive Park, Suite 221 Burlington, MA USA. Copyright 2014 by Black Duck Software, Inc. All rights reserved. All use of this documentation is subject to the license agreement between Black Duck Software, Inc. and the licensee. No part of the contents of this document may be reproduced or transmitted in any form or by any means without the prior written permission of Black Duck Software, Inc. Black Duck, Know Your Code, and the Black Duck logo are registered trademarks of Black Duck Software, Inc. in the United States and other jurisdictions. Black Duck Suite, Black Duck Code Center, Black Duck, Black Duck Protex, Black Duck Export, Black Duck Transact, and Koders are trademarks of Black Duck Software, Inc. All other trademarks or registered trademarks are the sole property of their respective owners.

3 Table of Contents TABLE OF CONTENTS 1 Overview What is included in the SDK? SDK jar files and libraries Installing the SDK Prerequisites SDK for Java installation Optionally load your samples into an Eclipse project Optionally access the SDK documentation from Eclipse Uninstalling the SDK Using the examples Common setup steps for all Java examples Setting the logging level in examples Suppressing the service information messages in examples Java examples Java example 1 Add a code location to a project Java example 2 Assign search permission Java example 3 Copy search permission Java example 4 Create a project Java example 5 Create a project with multiple code locations Java example 6 Remove a code location from a project Java example 7 Remove a search permission Java example 8 Sample of anonymous search Java example 9 Sample of basic search Java example 10 Sample search with filters Java example 11 Sample search with filters (single project) Java example 12 Set search access Java example 13 Update project attributes Utility Classes CodeSightServerProxyV2_1 Summary Page i

4 System Administrator s Guide Table of Contents 4.2 Helper methods initauthprops instrumentservice Service methods Page ii Error! Reference source not found.

5 Preface PREFACE This document serves as a supplement to the software development kit (SDK). It contains numerous illustrations on how to use the Java code examples. It also provides the instructions for installing the SDK. Target audience This manual is primarily for software engineers, tool developers, and system administrators who are responsible for the deployment and development of solutions. Programmers using the API should be familiar with application programming standards, such as the Simple Object Access Protocol (SOAP), the Web Services Description Language (WSDL), and XML Schema Definition (XSD) language. Related documents The documentation for the SDK consists of: Title File Description Online Javadocs Online access to the Javadoc created from the actual SDK sources. SDK Code Examples CodeSightSDK_Examples.pdf Instructions on how to run the included Java code examples. Page iii

6 Overview 1 OVERVIEW The SDK enables developers to integrate development into their native development processes. It provides API access to development features and services. This document supplements the online help, and provides some examples of how to use some of the common APIs and methods. It furnishes you with a set of practical examples on using the APIs and methods for the Java programming language. Java is an object-oriented programming language developed by Sun Microsystems. This document also describes how to install the SDK and how to use the various examples to perform the daily tasks and to automate various processes. The contents are meant to simplify using the SDK and to provide some typical illustrations on how to use several common code examples to help you get started. 1.1 What is included in the SDK? The SDK includes the following: A run-time license to use the APIs. Documentation containing a complete description of all of the API calls, including: Javadocs describing the current API calls SDK Code Examples (as a PDF file) Sample code in Java. Web Service Description Language (WSDL) files. 1.2 SDK jar files and libraries All of the jars included in your SDK package are examples, with the real SDK being the SOAP interface to. You can follow these to generate your own client libraries for your specific needs. If you want to use the client libraries that are generated with the samples, you need (at a minimum) codesight-sdk-client.jar. In addition, you need all the other jars on the lib dir as they build the cxf SOAP stack that this is built upon. To use the utility classes called in the sample programs, such as BDCodeSightSample.java or CodeSightServerProxyV20.java, then you can use: codesight-cxf-utilities.jar for the logging of soap messages codesight-sdk-utilities.jar for the classes mentioned above The actual sample programs are distributed as source and class files in the bin directory. For ease of use, they are not packaged in a jar file. Page 1

7 Installing the SDK 2 INSTALLING THE SDK In this release you must manually uncompress the SDK zip file downloaded from the Black Duck Software ftp site. There is no formal installer. This chapter provides you with the instructions on how to perform this operation. Note: Note: A standard license allows access through the graphical user interface. For programmatic access using the SOAP API a separate license for the Code Sight/SDK is required. This license is automatically checked and authentication is refused if the license is not purchased and activated by Black Duck Software. 2.1 Prerequisites Before implementing SOAP API from a client system, the following items must be installed and setup: You must have a running server that you can connect to. On that server, the sample programs need to connect as a user with the appropriate role for the function you are trying to do. For example, the sample program to create a project (see Java example 4 Create a project on page 13) requires a user whose role includes the Can create a project permission. The full list of roles is explained in the System Administrator's Guide and in the online help system (search for task roles.) Java examples require Java Development Kit (JDK) version 1.7 or higher. Your server must be licensed for the SDK. If your initial purchase included the SDK package, then your current license already allows access to the SDK. If you are adding SDK support, you will need to register your new license through the UI. Use the Settings Product Registration page to update your license. 2.2 SDK for Java installation This section explains how to install the SDK client and examples into your system. 1. Create a directory where you want to install the SDK on your local system. 2. Download the CodeSight-SDK.zip file and uncompress it in the new directory. Page 2

8 Installing the SDK After decompressing the files, the installation is complete Optionally load your samples into an Eclipse project This example creates an Eclipse project with all samples ready to be modified and executed. 1. Create a new Java project in Eclipse with a descriptive name. For example: codesight.sdksamples Page 3

9 Installing the SDK 2. Copy the downloaded SDK zip file into the workspace folder of the new project. For example: /workspace/codesight.sdksamples. 3. Unzip the file in that directory 4. Refresh you Eclipse project by right-clicking on the codesight.sdksamples node and selecting Refresh. 5. Delete the default src package folder from the codesight.sdksamples project. 6. Declare the examples/src as the source folder. a. Select folder examples/src b. Right-click and select Build Path Use as source folder. 7. Declare the examples/bin folder as the output folder. a. Select project. Page 4

10 Installing the SDK b. Right-click and select Build Path Configure Build Path. c. Select the source tab. d. For the Default output folder, click the Browse button. e. Select examples/bin. f. Click OK. g. Confirm deletion of old bin output folder including content. 8. Add all jars in the client-lib folder to classpath. a. Open the client-lib folder node. b. Select all jars in the folder. c. Right-click and select Build Path Add to Build Path. 9. Attach sources to all -specific jars. a. Open Referenced Libraries node. b. Select codesight-sdk-client.jar c. Right-click and select Build Path Configure Build Path. d. Select Libraries tab. e. Expand sdk-codesight-client.jar. i. Select Source Attachment. ii. iii. iv. Click Edit button Click Workspace button. Select the codesight-sdk-client-src.zip. v. Click OK (twice). f. Expand blackduck-cxf-utilities-1.0.jar. i. Select Source Attachment. ii. iii. iv. Click Edit button. Click Workspace button. Select the blackduck-cxf-utilities-1.0-src.zip. v. Click OK (twice). Page 5

11 Installing the SDK g. Expand codesight-sdk-utilities.jar. i. Select Source Attachment. ii. iii. iv. Click Edit button. Click Workspace button. Select the codesight-sdk-utilities-src.zip. v. Click OK (three times). 10. Complete a clean recompile of the project. a. Select the top codesight.sdksamples project. b. Select Project Clean. c. Clean only the single project. Now you can run any of the Sample classes by right-clicking on the java file in the tree and selecting Run As Java Application. When you run the project first time, the system shows the usage for this sample. The next step is to go to Run Configuration (which now has an entry for this class, due to the first failing run) and add the parameters as requested. Page 6

12 Installing the SDK Optionally access the SDK documentation from Eclipse Reference documentation for the SDK is provided in a Javadoc format, accessible from a server. You can optionally make this available within Eclipse. 1. Right-click on the codesight.sdksamples project you previously created and select Build Path Configure Build Path. 2. In the pop-up, select the Libraries tab. 3. Click to expand the entry for the codesight-sdk-client.jar. 4. Select Javadoc Location. 5. Click the Edit button. 6. In the pop-up, select Javadoc URL, and enter the location of your server with /sdkdocs/ appended to the address. For example: Page 7

13 Installing the SDK 7. Click OK to save your changes and exit. 8. In the left frame, select the Javadoc Location. 9. Enter the same location that you specified earlier. Page 8

14 Installing the SDK You can now use the Navigate Open External Javadoc option to access the SDK Javadocs while working with the sample programs. Note: This may be called Open Attached Javadoc in your version of Eclipse. 2.3 Uninstalling the SDK This section describes how to uninstall the SDK from your system. 1. Locate the folder where you installed the SDK sample files on your system. 2. Highlight the entire contents. 3. Delete all folders and files from your system. The uninstallation is complete. Page 9

15 Using the examples 3 USING THE EXAMPLES Reference documentation for all of the supported APIs and methods used in the application is available online from the Help page of the server you use. This manual supplements that documentation by providing examples, and it explains how to use and verify them. The examples are presented in a logical progression similar to how you would use them in an application. The concepts expressed for the Java examples can be applied to other programming languages, as well. Experienced programmers should be able to transition the concepts provided here to their respective programming tools. 3.1 Common setup steps for all Java examples The following are some common steps for all the examples: 1. Make sure you are in the SDK dev directory. 2. Open a command line window. 3. Locate the classes folder in the SDK, and display all files in that folder using the following: >cd <install dir>/examples/bin/com/blackducksoftware/sdk/codesight/client >dir (Windows) or >ls (Linux) The.class files are the Java example files Setting the logging level in examples Each example lets you set the logging level for the SOAP messages going to the server and being returned. Use the Dcodesight.sdk.debug=<logging level> parameter as follows: 0 compact pretty 1 compact 2 verbose secure 3 verbose secure pretty 4 verbose Page 10

16 Using the examples Example: Changing the logging level In this example, the CreateProject program is run from within Eclipse. 1. Right-click on the program and select Run As Java Application. You will get an error saying that there are insufficient parameters. 2. Right-click on the program again, and select Run As Run Configurations. 3. Select the Arguments tab and fill in the program arguments in the top box. All of the sample programs require a server, a username, and a password. They also require information specific to the task, such as project or SCM repository information. 4. In the lower box, enter the parameter to set the logging level to 4. Page 11

17 Using the examples 5. Click the Run button. The Eclipse console window shows the verbose version of the SOAP calls Suppressing the service information messages in examples You can suppress informational messages generated in the examples by changing the console logging level from INFO to WARNING. Start by creating a file etc/logging.properties with the following content: handlers= java.util.logging.consolehandler.level= WARNING Next, set the property in the command line (or in the Eclipse runtime settings) as follows, to execute the sample: -Djava.util.logging.config.file=etc/logging.properties 3.2 Java examples Note: The examples listed in this section are for Apache CXF For complete details on CXF, visit this website: This section provides examples on how to use several methods with Java. Java example 1 Add a code location to a project Java example 2 Assign search permission Java example 3 Copy search permission Java example 4 Create a project Java example 5 Create a project with multiple code locations Java example 6 Remove a code location from a project Java example 7 Remove a search permission Java example 8 Sample of anonymous search Java example 9 Sample of basic search Java example 10 Sample search with filters Java example 11 Sample search with filters (single project) Page 12

18 Using the examples Java example 12 Set search access Java example 13 Update project attribute Note: You need access to a server in order to use these examples Java example 1 Add a code location to a project This example demonstrates how to add a source code location to a project using AddProjectCodeLocation Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.addprojectcodelocation <CodeSightServerURL> <UserName> <password> <project name> <scm type> <connection string> <SCM username> <SCM password> <branch> Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.addprojectcodelocation sysadmin mypass testproject1 svn guestuser guestpass master Note that the arguments of password and project name are case sensitive Java example 2 Assign search permission This example demonstrates how to give a user search permission on a restricted project using AssignSearchPermission Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.assignsearchpermission <CodeSightServerURL> <UserName> <password> <project name> Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.assignsearchpermission sysadmin mypass testproject1 Page 13

19 Using the examples The sample program includes hard-coded references to the user and group. userrolenamepair.setprojectrolename("project Searcher"); userrolenamepair.setusername("test"); userrolenamelist.add(userrolenamepair); UserGroupRoleNamePair usergrouprolenamepair = new UserGroupRoleNamePair(); usergrouprolenamepair.setprojectrolename("project Searcher"); usergrouprolenamepair.setusergroupname("sample"); userrolenamelist.add(usergrouprolenamepair); projectapi.assignprojectsearchpermission(project.getprojectid(), userrolenamelist); Java example 3 Copy search permission This example demonstrates how to copy the search permissions (the list of users and groups with search access) on a restricted project to another project, using CopySearchPermission Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.copysearchpermission <CodeSightServerURL> <UserName> <password> <source project name> <target project name> Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.copysearchpermission sysadmin mypass testproject1 testproject Java example 4 Create a project This example demonstrates how to create a new project using CreateProject Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.createproject <CodeSightServerURL> <UserName> <password> <New project name> "<project description>" <Project URL> Page 14

20 Using the examples Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.createproject sysadmin mypass testproject1 "SDK test" This example creates an empty project with no source code. See Java example 1 Add a code location to a project for an example of how to add a source code location to this new project Java example 5 Create a project with multiple code locations This example demonstrates how to create a new project using CreateProjectWithMultipleCodeLoc Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.createprojectwithmultiplecodeloc <CodeSightServerURL> <UserName> <password> <New project name> "<project description>" <Project URL> <scm type> <connection string> <SCM username> <SCM password> <branch> Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.createprojectwithmultiplecodeloc sysadmin mypass testproject1 "SDK test" svn guestuser guestpass trunk The sample program creates a project with one code location, but it could be modified to add multiple locations Java example 6 Remove a code location from a project This example demonstrates how to remove a code location from a project using RemoveProjectCodeLocation. Page 15

21 Using the examples Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.removeprojectcodelocation <CodeSightServerURL> <UserName> <password> <project name> <connection string> <branch> Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.removeprojectcodelocation sysadmin mypass testproject1 master Java example 7 Remove a search permission This example illustrates how to restrict access to a project using RemoveSearchPermission Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.removesearchpermission <CodeSightServerURL> <UserName> <password> <project name> Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.removesearchpermission sysadmin mypass testproj Java example 8 Sample of anonymous search This example demonstrates how to submit a search query using SampleAnonymousSearch Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.sampleanonymoussearch <CodeSightServerURL> <UserName> <password> "<search query>" Page 16

22 Using the examples Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.sampleanonymoussearch sysadmin mypass "search query" Java example 9 Sample of basic search This example demonstrates how to submit a search query using SampleSearch Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.samplesearch <CodeSightServerURL> <UserName> <password> "<search query>" Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.samplesearch sysadmin mypass "search query" Java example 10 Sample search with filters This example demonstrates how to create a new project using SampleSearchWithFacetFilters Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.samplesearchwithfacetfilters <CodeSightServerURL> <UserName> <password> "<search query>" Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.samplesearchwithfacetfilters sysadmin mypass "search query" Java example 11 Sample search with filters (single project) This example demonstrates how to create a new project using Page 17

23 Using the examples SampleSearchWithFacetFiltersSingleProject Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.samplesearchwithfacetfilterssingleproject <CodeSightServerURL> <UserName> <password> "<search query>" Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.samplesearchwithfacetfilterssingleproject sysadmin mypass "search query" Java example 12 Set search access This example demonstrates how to set the access on a project using SetSearchAccess Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.setsearchaccess <CodeSightServerURL> <UserName> <password> <project name> <search access type> Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.setsearchaccess sysadmin mypass testproject1 HIDE Valid access types are: SHOW, HIDE, and RESTRICT Java example 13 Update project attributes This example illustrates how to change the description field of a project Procedure: java -Djava.util.logging.config.file=etc/logging.properties classpath "<classpath>" com.blackducksoftware.sdk.codesight.client.updateprojectattributes <CodeSightServerURL> <UserName> <password> <Project name> "<new description>" Page 18

24 Using the examples Example in Windows: java -classpath "examples/bin;lib/*" com.blackducksoftware.sdk.codesight.client.updateprojectattributes sysadmin mypass testproj1 "SDK test" Page 19

25 Utility Classes 4 UTILITY CLASSES The following types of utility classes are available in the SDK: CodeSightServerProxyV2_1 Summary Helper methods Service methods 4.1 CodeSightServerProxyV2_1 Summary A server proxy class makes it convenient to connect to a server and retrieve various service objects How to use: Create an instance of a server proxy, supplying all required parameters For example: CodeSightServerProxyV2_1 CodeSightServerProxyV2_0=new CodeSightServerProxyV2_1 (ServerURI,userName,password); CodeSightServerProxyV2_0=new CodeSightServerProxyV2_1 ("[email protected]","[email protected]", testing); 4.2 Helper methods The following helper methods are available. initauthprops instrumentservice initauthprops Initialize the username and password authentication properties How to use: CodeSightServerProxyV2_1.initAuthProps(userName, password); For example: CodeSightServerProxyV2_1.initAuthProps("[email protected]", "testing"); Page 20

26 Utility Classes instrumentservice Instrument the service port object with authentication information and the appropriate handlers How to use: CodeSightServerProxyV2_1.instrumentService(serviceApi,userName,password,timeout); //timeout is optional. "testing"); 4.3 Service methods These methods return the service object How to use: CodeSightServerProxyV2_1.getXXXApi(); For example: Suppose you need a service object for the project API. CodeSightServerProxyV2_1.getProjectApi(); Page 21