How to Use the Code Sight SDK Code Examples

Transcription

How to Use the Code Sight
SDK Code Examples
Version 2.2
This document updated June 12, 2012.
Please send your comments and suggestions to:
Black Duck Software, Incorporated
8 New England Executive Park
Burlington, MA – 01803 USA
Copyright © 2011-2012 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 help system 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 Code Sight, 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.
HOW TO USE THE CODE EXAMPLES
Table of Contents
1
1.1
1.2
1.3
2
OVERVIEW .................................................................................. 7
PURPOSE OF THIS DOCUMENT ..................................................................7
WHAT'S INCLUDED IN THE SDK .................................................................7
SDK JAR FILES AND LIBRARIES .................................................................7
INSTALLING THE SDK ..................................................................... 9
2.1
INSTALLATION OVERVIEW ......................................................................9
2.2
PREREQUISITES ................................................................................9
2.3
CODE SIGHT SDK FOR JAVA INSTALLATION .....................................................9
2.3.1
Optionally Load Your Samples into an Eclipse Project ......................... 10
2.3.2
Optionally Access the SDK Documentation from Eclipse ....................... 13
2.4
UNINSTALLING THE SDK ..................................................................... 15
3
USING THE EXAMPLES ................................................................... 17
3.1
INTRODUCTION .............................................................................. 17
3.1.1
Common Setup Steps for All Java Examples ..................................... 17
3.1.2
Setting the Logging Level in Examples ............................................ 17
3.1.3
Suppressing the Service Information Messages in Examples ................... 19
3.2
JAVA EXAMPLES.............................................................................. 19
3.2.1
Java Example 1—Add a Code Location to a Project ............................. 20
3.2.2
Java Example 2—Assign Search Permission ....................................... 21
3.2.3
Java Example 3—Copy Search Permission ........................................ 22
3.2.4
Java Example 4—Create a Project ................................................. 23
3.2.5
Java Example 5—Create a Project with Multiple Code Locations ............. 24
3.2.6
Java Example 6—Remove a Code Location from a Project .................... 25
3.2.7
Java Example 7—Remove a Search Permission .................................. 26
3.2.8
Java Example 8—Sample of Anonymous Search ................................. 27
3.2.9
Java Example 9—Sample of Basic Search ......................................... 28
3.2.10 Java Example 10—Sample Search with Filters ................................... 29
3.2.11 Java Example 11—Sample Search with Filters (single project)................ 30
3.2.12 Java Example 12—Set Search Access .............................................. 31
3.2.13 Java Example 13—Update Project Attributes .................................... 32
4
UTILITY CLASSES ......................................................................... 33
4.1
CODESIGHTSERVERPROXYV2_1 SUMMARY .................................................... 33
4.2
HELPER METHODS ........................................................................... 33
4.2.1
initAuthProps ......................................................................... 33
4.2.2
instrumentService ................................................................... 33
4.3
SERVICE METHODS ........................................................................... 34
iii
HOW
TO
USE
THE
C OD E EX AMP LES
iv
Figures
FIGURE 1 SDK MAIN DIRECTORY CONTENTS ................................................................................... 10
v
Preface
This document serves as a supplement to the Code Sight 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 Code Sight 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.
CONTENTS OVERVIEW
Chapter 1: Overview—Describes the purpose of this document and mentions the features and benefits.
Chapter 2: Installing the SDK—Describes what is covered in the SDK installation process. It gives installation
directions and describes the book's contents (in detail). It also tells how to uninstall the SDK.
Chapter 3: Using the Examples—Provides practical examples of how to use the API methods in a step-by-step
format. In each section, there are examples of common operations designed to help you get familiar with the APIs.
See the online help for listings of all the Code Sight SDK methods.
Chapter 4: Utility Classes
HOW TO USE THIS BOOK
This document contains a Table of Contents and a List of Figures. Each is included to enable easy searches to
locate specific topics.
HOW
TO
USE
THE
C OD E EX AMP LES
vi
RELATED DOCUMENTS
The documentation for the Code Sight SDK consists of:
Title
File
Description
Online Javadocs
http://<Code Sightserver>/sdkdocs/index.html
Online access to the Javadoc created from the
actual SDK sources.
How to Use the Code Sight
SDK Code Examples
CodeSightSDK_Examples.pdf
Instructions on how to run the included Java
code examples.
1
OVERVIEW
1 OVERVIEW
1.1 Purpose of This Document
The Software Development Kit (SDK) enables developers to integrate Code Sight 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.2 What's 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:
o
Javadocs describing the current API calls
o
How to Use the Code Sight SDK Code Examples (as a PDF file)
•
Sample code in Java.
•
Web Service Description Language (WSDL) files.
1.3 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 Code
Sight. 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:
HOW
TO
USE
THE
•
codesight-cxf-utilities.jar -- for the logging of soap messages
•
and codesight-sdk-utilities.jar -- for the classes mentioned above
C OD E EX AMP LES
8
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.
INSTALLING THE SDK
2
2 INSTALLING THE SDK
2.1 Installation Overview
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: A standard Code Sight license allows access through the graphical user interface. For
programmatic access using the Code Sight 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.2 Prerequisites
Before implementing SOAP API from a client system, the following items must be installed and setup:
•
You must have a running Code Sight 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 Section 3.2.1) requires a user who’s role includes the “Can create
a project” permission. The full list of roles is explained in the Code Sight System Administrator's Guide and in
the online help (search for "task roles".)
•
Java examples require Java JDK version 1.6.x or higher.
•
Your Code Sight server must be licensed for the SDK. If your initial Code Sight 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 Code Sight UI. Use the Settings 
Product Registration page to update your license.
2.3 Code Sight SDK for Java Installation
This section explains how to install the Code Sight 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.
10
Figure 1 SDK Main Directory Contents
After decompressing the files, the installation is complete.
2.3.1 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
2.
Copy the downloaded Code Sight 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. (Right-click on the codesight.sdksamples node and select 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.
8.
9.
Declare the examples/bin folder as the output folder.
a.
Select project
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 and select examples/bin
e.
Click OK
f.
Confirm deletion of old output folder "bin", including content
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
Attach sources to all Code Sight 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
1.
Select Source Attachment
2.
Click Edit button
3.
Click Workspace button
4.
Select the codesight-sdk-client-src.zip
11
5.
f.
g.
12
Click OK (twice)
Expand blackduck-cxf-utilities-1.0.jar
1.
2.
Click Edit button
3.
4.
Select the blackduck-cxf-utilities-1.0-src.zip
5.
Click OK (twice)
Expand codesight-sdk-utilities.jar
1.
2.
Click Edit button
3.
4.
Select the codesight-sdk-utilities-src.zip
5.
Click OK (three times)
10. Complete a clean recompile of the project
a.
Select the top codesight.sdksamples project
b. 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 it the 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.
13
2.3.2 Optionally Access the SDK Documentation from Eclipse
Reference documentation for the SDK is provided in a Javadoc format, accessible from a Code Sight server. You
can optionally make this available within Eclipse.
1.
Right click on the codesight.sdksamples project created in the previous section, and choose: 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", and click the Edit button.
5.
In the pop-up, select "Javadoc URL", and enter the location of your Code Sight server with "/sdk-docs/"
appended to the address. For example: http://codesight-server/sdk-docs/.
6.
7.
8.
Click OK to save your changes and exit.
In the left frame, select the Javadoc Location.
Enter the same location that you specified earlier.
14
You can now use the Navigate  Open External Javadoc option to access the Code Sight SDK Javadocs while
working with the sample programs. (This may be called Open Attached Javadoc in your version of Eclipse.)
2.4 Uninstalling the SDK
This section describes how to uninstall the SDK from your system.
To uninstall the SDK, follow these steps:
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.
Uninstallation is complete.
.
15
USING THE EXAMPLES
3
3 USING THE EXAMPLES
3.1 Introduction
Reference documentation for all of the supported APIs and methods used in the Code Sight application is available
online from the Help page of the Code Sight 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.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.
3.1.2 Setting the Logging Level in Examples
Each example allows you to 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
USING
THE
EXAMPLES
18
Example 1: 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.
2.
You will get an error saying that there are insufficient parameters.
3.
Right click on the program again, and choose Run As  Run Configurations.
4.
Select the Arguments tab and fill in the program arguments in the top box. All of the sample programs require a
Code Sight server, a username, and a password. They also require information specific to the task, such as project
or SCM repository information.
5.
In the lower box, enter the parameter to set the logging level to 4.
6.
Click the Run button.
USING
THE
EXAMPLES
19
The Eclipse console window shows the verbose version of the SOAP calls.
3.1.3 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 2.0.11. For complete details on CXF, visit this web
site: http://cxf.apache.org/
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)
•
Java Example 12—Set Search Access
•
Java Example 13—Update Project Attribute
Note: You need access to a Code Sight server in order to use these examples.
USING
THE
EXAMPLES
20
3.2.1 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:
Windows:
java -classpath "examples/bin;lib/*"
com.blackducksoftware.sdk.codesight.client.AddProjectCodeLocation
http://codesight-server sysadmin mypass
testproject1 svn http://svn.apache.org/repos/asf/ant/core/trunk/src
guestuser guestpass master
Note that the arguments of password and project name are case sensitive.
USING
THE
EXAMPLES
21
3.2.2 Java Example 2—Assign Search Permission
This example demonstrates how to give a user search permission on a restricted project using
AssignSearchPermission.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.AssignSearchPermission
<project name>
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.AssignSearchPermission
testproject1
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);
USING
THE
EXAMPLES
22
3.2.3 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:
com.blackducksoftware.sdk.codesight.client.CopySearchPermission
<source project name> <target project name>
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.CopySearchPermission
testproject1 testproject2
USING
THE
EXAMPLES
23
3.2.4 Java Example 4—Create a Project
This example demonstrates how to create a new Code Sight project using CreateProject.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.CreateProject
<New project name> "<project description>" <Project URL>
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.CreateProject http://codesightserver sysadmin mypass
testproject1 "SDK test" http://bdstest.com
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.
USING
THE
EXAMPLES
24
3.2.5 Java Example 5—Create a Project with Multiple Code Locations
This example demonstrates how to create a new Code Sight project using
CreateProjectWithMultipleCodeLoc.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.CreateProjectWithMultipleCodeLoc
<New project name> "<project description>" <Project URL>
<scm type> <connection string>
<SCM username> <SCM password> <branch>
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.CreateProjectWithMultipleCodeLoc
testproject1 "SDK test" http://bdstest.com
svn http://svn.apache.org/repos/asf/ant/core/trunk/src
guestuser guestpass trunk
The sample program creates a project with one code location, but it could be modified to add multiple locations.
USING
THE
EXAMPLES
25
3.2.6 Java Example 6—Remove a Code Location from a Project
This example demonstrates how to remove a code location from a project using RemoveProjectCodeLocation.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.RemoveProjectCodeLocation
<project name> <connection string> <branch>
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.RemoveProjectCodeLocation
testproject1 http://svn.apache.org/repos/asf/ant/core/trunk/src master
USING
THE
EXAMPLES
26
3.2.7 Java Example 7—Remove a Search Permission
This example illustrates how to restrict access to a project using RemoveSearchPermission.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.RemoveSearchPermission
<project name>
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.RemoveSearchPermission
testproj1
T
USING
THE
EXAMPLES
27
3.2.8 Java Example 8—Sample of Anonymous Search
This example demonstrates how to submit a search query using SampleAnonymousSearch.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.SampleAnonymousSearch
"<search query>"
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.SampleAnonymousSearch
"search query"
USING
THE
EXAMPLES
28
3.2.9 Java Example 9—Sample of Basic Search
This example demonstrates how to submit a search query using SampleSearch.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.SampleSearch
"<search query>"
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.SampleSearch http://codesightserver sysadmin mypass
"search query"
USING
3.2.10
THE
EXAMPLES
29
Java Example 10—Sample Search with Filters
This example demonstrates how to create a new Code Sight project using SampleSearchWithFacetFilters.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.SampleSearchWithFacetFilters
"<search query>"
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.SampleSearchWithFacetFilters
http://codesight-server sysadmin mypass "search query"
USING
3.2.11
THE
EXAMPLES
30
Java Example 11—Sample Search with Filters (single project)
This example demonstrates how to create a new Code Sight project using
SampleSearchWithFacetFiltersSingleProject.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.SampleSearchWithFacetFiltersSingleProject
"<search query>"
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.SampleSearchWithFacetFiltersSingle
Project http://codesight-server sysadmin mypass "search query"
USING
3.2.12
THE
EXAMPLES
31
Java Example 12—Set Search Access
This example demonstrates how to set the access on a project using SetSearchAccess.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.SetSearchAccess
<project name> <search access type>
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.SetSearchAccess http://codesightserver sysadmin mypass
testproject1 HIDE
Valid access types are: SHOW, HIDE, and RESTRICT.
USING
3.2.13
THE
EXAMPLES
32
Java Example 13—Update Project Attributes
This example illustrates how to change the description field of a project.
PROCEDURE:
com.blackducksoftware.sdk.codesight.client.UpdateProjectAttributes
<Project name> "<new description>"
EXAMPLE:
Windows:
com.blackducksoftware.sdk.codesight.client.UpdateProjectAttributes
testproj1 "SDK test"
UTILITY CLASSES
4
4 UTILITY CLASSES
4.1 CodeSightServerProxyV2_1 Summary
A server proxy class makes it convenient to connect to a Code Sight server and retrieve various service objects.
HOW TO USE:
Create an instance of a Code Sight 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
4.2.1 initAuthProps
Initialize the username and password authentication properties.
HOW TO USE:
CodeSightServerProxyV2_1.initAuthProps(userName, password);
FOR EXAMPLE:
CodeSightServerProxyV2_1.initAuthProps("[email protected]", "testing");
4.2.2 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.
CodeSightServerProxyV2_1.instrumentService("ApplicationApi","[email protected]",
"testing");
UTILITY CLASSES
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();
34

How to Use the Code Sight SDK Code Examples

Transcription

Similar documents

You can count on us.”

Java Central Update 1-9-14

Cover

vTuner Internet Radio Rapid Prototyping SDK USB

Wide Temperature Quad SD Mini-PCIe Capture Card

Document 6506614

Portfolio Christoph Gerstner - game