1# Google Natural Language Client for Java 2 3Java idiomatic client for [Natural Language][product-docs]. 4 5[![Maven][maven-version-image]][maven-version-link] 6![Stability][stability-image] 7 8- [Product Documentation][product-docs] 9- [Client Library Documentation][javadocs] 10 11 12## Quickstart 13 14 15If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file: 16 17```xml 18<dependencyManagement> 19 <dependencies> 20 <dependency> 21 <groupId>com.google.cloud</groupId> 22 <artifactId>libraries-bom</artifactId> 23 <version>26.12.0</version> 24 <type>pom</type> 25 <scope>import</scope> 26 </dependency> 27 </dependencies> 28</dependencyManagement> 29 30<dependencies> 31 <dependency> 32 <groupId>com.google.cloud</groupId> 33 <artifactId>google-cloud-language</artifactId> 34 </dependency> 35``` 36 37If you are using Maven without the BOM, add this to your dependencies: 38 39<!-- {x-version-update-start:google-cloud-language:released} --> 40 41```xml 42<dependency> 43 <groupId>com.google.cloud</groupId> 44 <artifactId>google-cloud-language</artifactId> 45 <version>2.18.0</version> 46</dependency> 47``` 48 49If you are using Gradle without BOM, add this to your dependencies: 50 51```Groovy 52implementation 'com.google.cloud:google-cloud-language:2.18.0' 53``` 54 55If you are using SBT, add this to your dependencies: 56 57```Scala 58libraryDependencies += "com.google.cloud" % "google-cloud-language" % "2.18.0" 59``` 60<!-- {x-version-update-end} --> 61 62## Authentication 63 64See the [Authentication][authentication] section in the base directory's README. 65 66## Authorization 67 68The client application making API calls must be granted [authorization scopes][auth-scopes] required for the desired Natural Language APIs, and the authenticated principal must have the [IAM role(s)][predefined-iam-roles] required to access GCP resources using the Natural Language API calls. 69 70## Getting Started 71 72### Prerequisites 73 74You will need a [Google Cloud Platform Console][developer-console] project with the Natural Language [API enabled][enable-api]. 75You will need to [enable billing][enable-billing] to use Google Natural Language. 76[Follow these instructions][create-project] to get your project set up. You will also need to set up the local development environment by 77[installing the Google Cloud Command Line Interface][cloud-cli] and running the following commands in command line: 78`gcloud auth login` and `gcloud config set project [YOUR PROJECT ID]`. 79 80### Installation and setup 81 82You'll need to obtain the `google-cloud-language` library. See the [Quickstart](#quickstart) section 83to add `google-cloud-language` as a dependency in your code. 84 85## About Natural Language 86 87 88[Natural Language][product-docs] provides natural language understanding technologies to developers, including sentiment analysis, entity analysis, entity sentiment analysis, content classification, and syntax analysis. This API is part of the larger Cloud Machine Learning API family. 89 90See the [Natural Language client library docs][javadocs] to learn how to 91use this Natural Language Client Library. 92 93 94#### Analyzing sentiment 95With Cloud Natural Language, you can analyze the sentiment of text. Add the following imports at the top of your file: 96 97``` java 98import com.google.cloud.language.v1.LanguageServiceClient; 99import com.google.cloud.language.v1.Document; 100import com.google.cloud.language.v1.Document.Type; 101import com.google.cloud.language.v1.Sentiment; 102``` 103Then, to analyze the sentiment of some text, use the following code: 104 105``` java 106// Instantiates a client 107LanguageServiceClient language = LanguageServiceClient.create(); 108 109// The text to analyze 110String[] texts = {"I love this!", "I hate this!"}; 111for (String text : texts) { 112 Document doc = Document.newBuilder().setContent(text).setType(Type.PLAIN_TEXT).build(); 113 // Detects the sentiment of the text 114 Sentiment sentiment = language.analyzeSentiment(doc).getDocumentSentiment(); 115 116 System.out.printf("Text: \"%s\"%n", text); 117 System.out.printf( 118 "Sentiment: score = %s, magnitude = %s%n", 119 sentiment.getScore(), sentiment.getMagnitude()); 120} 121``` 122 123#### Complete source code 124 125In [AnalyzeSentiment.java](https://github.com/googleapis/google-cloud-java/blob/master/google-cloud-examples/src/main/java/com/google/cloud/examples/language/snippets/AnalyzeSentiment.java) we put the code shown above into a complete program. 126 127 128 129 130## Troubleshooting 131 132To get help, follow the instructions in the [shared Troubleshooting document][troubleshooting]. 133 134## Transport 135 136Natural Language uses gRPC for the transport layer. 137 138## Supported Java Versions 139 140Java 8 or above is required for using this client. 141 142Google's Java client libraries, 143[Google Cloud Client Libraries][cloudlibs] 144and 145[Google Cloud API Libraries][apilibs], 146follow the 147[Oracle Java SE support roadmap][oracle] 148(see the Oracle Java SE Product Releases section). 149 150### For new development 151 152In general, new feature development occurs with support for the lowest Java 153LTS version covered by Oracle's Premier Support (which typically lasts 5 years 154from initial General Availability). If the minimum required JVM for a given 155library is changed, it is accompanied by a [semver][semver] major release. 156 157Java 11 and (in September 2021) Java 17 are the best choices for new 158development. 159 160### Keeping production systems current 161 162Google tests its client libraries with all current LTS versions covered by 163Oracle's Extended Support (which typically lasts 8 years from initial 164General Availability). 165 166#### Legacy support 167 168Google's client libraries support legacy versions of Java runtimes with long 169term stable libraries that don't receive feature updates on a best efforts basis 170as it may not be possible to backport all patches. 171 172Google provides updates on a best efforts basis to apps that continue to use 173Java 7, though apps might need to upgrade to current versions of the library 174that supports their JVM. 175 176#### Where to find specific information 177 178The latest versions and the supported Java versions are identified on 179the individual GitHub repository `github.com/GoogleAPIs/java-SERVICENAME` 180and on [google-cloud-java][g-c-j]. 181 182## Versioning 183 184 185This library follows [Semantic Versioning](http://semver.org/). 186 187 188 189## Contributing 190 191 192Contributions to this library are always welcome and highly encouraged. 193 194See [CONTRIBUTING][contributing] for more information how to get started. 195 196Please note that this project is released with a Contributor Code of Conduct. By participating in 197this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more 198information. 199 200 201## License 202 203Apache 2.0 - See [LICENSE][license] for more information. 204 205## CI Status 206 207Java Version | Status 208------------ | ------ 209Java 8 | [![Kokoro CI][kokoro-badge-image-2]][kokoro-badge-link-2] 210Java 8 OSX | [![Kokoro CI][kokoro-badge-image-3]][kokoro-badge-link-3] 211Java 8 Windows | [![Kokoro CI][kokoro-badge-image-4]][kokoro-badge-link-4] 212Java 11 | [![Kokoro CI][kokoro-badge-image-5]][kokoro-badge-link-5] 213 214Java is a registered trademark of Oracle and/or its affiliates. 215 216[product-docs]: https://cloud.google.com/natural-language/docs/ 217[javadocs]: https://cloud.google.com/java/docs/reference/google-cloud-language/latest/overview 218[kokoro-badge-image-1]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java7.svg 219[kokoro-badge-link-1]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java7.html 220[kokoro-badge-image-2]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8.svg 221[kokoro-badge-link-2]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8.html 222[kokoro-badge-image-3]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-osx.svg 223[kokoro-badge-link-3]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-osx.html 224[kokoro-badge-image-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-win.svg 225[kokoro-badge-link-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-win.html 226[kokoro-badge-image-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java11.svg 227[kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java11.html 228[stability-image]: https://img.shields.io/badge/stability-stable-green 229[maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-language.svg 230[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-language/2.15.0 231[authentication]: https://github.com/googleapis/google-cloud-java#authentication 232[auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes 233[predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles 234[iam-policy]: https://cloud.google.com/iam/docs/overview#cloud-iam-policy 235[developer-console]: https://console.developers.google.com/ 236[create-project]: https://cloud.google.com/resource-manager/docs/creating-managing-projects 237[cloud-cli]: https://cloud.google.com/cli 238[troubleshooting]: https://github.com/googleapis/google-cloud-java/blob/main/TROUBLESHOOTING.md 239[contributing]: https://github.com/googleapis/google-cloud-java/blob/main/CONTRIBUTING.md 240[code-of-conduct]: https://github.com/googleapis/google-cloud-java/blob/main/CODE_OF_CONDUCT.md#contributor-code-of-conduct 241[license]: https://github.com/googleapis/google-cloud-java/blob/main/LICENSE 242[enable-billing]: https://cloud.google.com/apis/docs/getting-started#enabling_billing 243[enable-api]: https://console.cloud.google.com/flows/enableapi?apiid=language.googleapis.com 244[libraries-bom]: https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM 245[shell_img]: https://gstatic.com/cloudssh/images/open-btn.png 246 247[semver]: https://semver.org/ 248[cloudlibs]: https://cloud.google.com/apis/docs/client-libraries-explained 249[apilibs]: https://cloud.google.com/apis/docs/client-libraries-explained#google_api_client_libraries 250[oracle]: https://www.oracle.com/java/technologies/java-se-support-roadmap.html 251[g-c-j]: http://github.com/googleapis/google-cloud-java 252
