Changes to README (#1168)

* readme update #1 * readme update #2 * readme update #2 * fixing HTML table * fixing HTML table * added a vmss example * editorial * editorial * editorial * first draft * Editorial * Editorial * added hyperlinks * added hyperlinks * linked * editorial * editorial * added one more sample
Azure · Oct 6, 2016 · 2f87745 · 2f87745
1 parent 25f6554
commit 2f87745
Show file tree

Hide file tree

Showing 2 changed files with 256 additions and 67 deletions.
diff --git a/README.md b/README.md
@@ -2,12 +2,12 @@
 
 #Azure Management Libraries for Java
 
-This README is based on the latest released preview version (1.0.0-beta2). If you are looking for other releases, see [More Information](#more-information)
+This README is based on the latest released preview version (1.0.0-beta3). If you are looking for other releases, see [More Information](#more-information)
 
 The Azure Management Libraries for Java is a higher-level, object-oriented API for managing Azure resources.
 
 
-> **1.0.0-beta2** is a developer preview that supports major parts of Azure Compute, Storage, Networking and Resource Manager. The next preview version of the Azure Management Libraries for Java is a work in-progress. We will be adding support for more Azure services and tweaking the API over the next few months.
+> **1.0.0-beta3** is a developer preview that supports major parts of Azure Virtual Machines, Virtual Machine Scale Sets, Storage, Networking, Resource Manager, Key Vault and Batch. The next preview version of the Azure Management Libraries for Java is a work in-progress. We will be adding support for more Azure services and tweaking the API over the next few months.
 
 **Azure Authentication**
 
@@ -17,14 +17,14 @@ The `Azure` class is the simplest entry point for creating and interacting with
 
 **Create a Virtual Machine**
 
-You can create a virtual machine instance by using the `define() … create()` method chain.
+You can create a virtual machine instance by using a `define() … create()` method chain.
 
 ```java
 System.out.println("Creating a Linux VM");
 
 VirtualMachine linuxVM = azure.virtualMachines().define("myLinuxVM")
 	.withRegion(Region.US_EAST)
-	.withNewResourceGroup("myResourceGroup")
+	.withNewResourceGroup(rgName)
 	.withNewPrimaryNetwork("10.0.0.0/28")
 	.withPrimaryPrivateIpAddressDynamic()
 	.withNewPrimaryPublicIpAddress("mylinuxvmdns")
@@ -39,7 +39,7 @@ System.out.println("Created a Linux VM: " + linuxVM.id());
 
 **Update a Virtual Machine**
 
-You can update a virtual machine instance by using the `update() … apply()` method chain.
+You can update a virtual machine instance by using an `update() … apply()` method chain.
 
 ```java
 linuxVM.update()
@@ -49,10 +49,33 @@ linuxVM.update()
     .attach()
     .apply();
 ```
+**Create a Virtual Machine Scale Set**
+
+You can create a virtual machine scale set instance by using another `define() … create()` method chain.
+
+```java
+ VirtualMachineScaleSet virtualMachineScaleSet = azure.virtualMachineScaleSets()
+     .define(vmssName)
+     .withRegion(Region.US_EAST)
+     .withExistingResourceGroup(rgName)
+     .withSku(VirtualMachineScaleSetSkuTypes.STANDARD_D3_V2)
+     .withExistingPrimaryNetworkSubnet(network, "Front-end")
+     .withPrimaryInternetFacingLoadBalancer(loadBalancer1)
+     .withPrimaryInternetFacingLoadBalancerBackends(backendPoolName1, backendPoolName2)
+     .withPrimaryInternetFacingLoadBalancerInboundNatPools(natPool50XXto22, natPool60XXto23)
+     .withoutPrimaryInternalLoadBalancer()
+     .withPopularLinuxImage(KnownLinuxVirtualMachineImage.UBUNTU_SERVER_16_04_LTS)
+     .withRootUserName(userName)
+     .withSsh(sshKey)
+     .withNewStorageAccount(storageAccountName1)
+     .withNewStorageAccount(storageAccountName2)
+     .withCapacity(3)
+     .create();
+```
 
 **Create a Network Security Group**
 
-You can create a network security group instance by using the `define() … create()` method chain.
+You can create a network security group instance by using another `define() … create()` method chain.
 
 ```java
 NetworkSecurityGroup frontEndNSG = azure.networkSecurityGroups().define(frontEndNSGName)
@@ -84,80 +107,94 @@ NetworkSecurityGroup frontEndNSG = azure.networkSecurityGroups().define(frontEnd
 
 #Sample Code
 
-You can find plenty of sample code that illustrates management scenarios in Azure Compute, Storage, Network and Resource Manager … 
-
-
-
-- [Manage virtual machine](https://github.com/Azure-Samples/compute-java-manage-vm)
-- [Manage availability set](https://github.com/Azure-Samples/compute-java-manage-availability-sets)
-- [List virtual machine images](https://github.com/Azure-Samples/compute-java-list-vm-images)
-- [Manage storage accounts](https://github.com/Azure-Samples/storage-java-manage-storage-accounts)
-- [Manage virtual network](https://github.com/Azure-Samples/network-java-manage-virtual-network)
-- [Manage network interface](https://github.com/Azure-Samples/network-java-manage-network-interface)
-- [Manage network security group](https://github.com/Azure-Samples/network-java-manage-network-security-group)
-- [Manage IP address](https://github.com/Azure-Samples/network-java-manage-ip-address)
-- [Manage resource groups](https://github.com/Azure-Samples/resources-java-manage-resource-group)
-- [Manage resources](https://github.com/Azure-Samples/resources-java-manage-resource)
-- [Deploy resources with ARM templates](https://github.com/Azure-Samples/resources-java-deploy-using-arm-template)
-- Deploy resources with ARM templates (with progress). Link will become available as soon as the sample is ready
+You can find plenty of sample code that illustrates management scenarios in Azure Virtual Machines, Virtual Machine Scale Sets, Storage, Networking, Resource Manager, Key Vault and Batch … 
+
+<table>
+  <tr>
+    <th>Service</th>
+    <th>Management Scenario</th>
+  </tr>
+  <tr>
+    <td>Virtual Machines</td>
+    <td><ul style="list-style-type:circle">
+<li><a href="https://github.com/Azure-Samples/compute-java-manage-vm">Manage virtual machine</a></li>
+<li><a href="https://github.com/Azure-Samples/compute-java-manage-availability-sets"> Manage availability set</li>
+<li><a href="https://github.com/Azure-Samples/compute-java-list-vm-images">List virtual machine images</li>
+<li><a href="https://github.com/Azure-Samples/compute-java-manage-virtual-machine-using-vm-extensions">Manage virtual machines using VM extensions</li>
+<li><a href="https://github.com/Azure-Samples/compute-java-list-vm-extension-images">List virtual machine extension images</li>
+</ul>
+</td>
+  </tr>
+  <tr>
+    <td>Virtual Machines - parallel execution</td>
+    <td><ul style="list-style-type:circle">
+<li><a href="http://github.com/azure-samples/compute-java-manage-virtual-machines-in-parallel">Create multiple virtual machines in parallel</li>
+<li><a href="http://github.com/azure-samples/compute-java-manage-virtual-machines-with-network-in-parallel">Create multiple virtual machines with network in parallel</li>
+</ul></td>
+  </tr>
+  <tr>
+    <td>Virtual Machine Scale Sets</td>
+    <td><ul style="list-style-type:circle">
+<li><a href="https://github.com/Azure-Samples/compute-java-manage-virtual-machine-scale-sets">Manage virtual machine scale sets (behind an Internet facing load balancer)</a></li>
+</ul></td>
+  </tr>
+  <tr>
+    <td>Storage</td>
+    <td><ul style="list-style-type:circle">
+<li><a href="https://github.com/Azure-Samples/storage-java-manage-storage-accounts">Manage storage accounts</a></li>
+</ul></td>
+  </tr>
+  <tr>
+    <td>Network</td>
+    <td><ul style="list-style-type:circle">
+
+<li><a href="https://github.com/Azure-Samples/network-java-manage-virtual-network">Manage virtual network</a></li>
+<li><a href="https://github.com/Azure-Samples/network-java-manage-network-interface">Manage network interface</a></li>
+<li><a href="https://github.com/Azure-Samples/network-java-manage-network-security-group">Manage network security group</a></li>
+<li><a href="https://github.com/Azure-Samples/network-java-manage-ip-address">Manage IP address</a></li>
+<li><a href="https://github.com/Azure-Samples/network-java-manage-internet-facing-load-balancers">Manage Internet facing load balancers</a></li>
+<li><a href="https://github.com/Azure-Samples/network-java-manage-internal-load-balancers">Manage internal load balancers</a></li>
+</ul>
+</td>
+  </tr>
+  <tr>
+    <td>Resource Groups</td>
+    <td><ul style="list-style-type:circle">
+<li><a href="https://github.com/Azure-Samples/resources-java-manage-resource-group">Manage resource groups</a></li>
+<li><a href="https://github.com/Azure-Samples/resources-java-manage-resource">Manage resources</a></li>
+<li><a href="https://github.com/Azure-Samples/resources-java-deploy-using-arm-template">Deploy resources with ARM templates</a></li>
+<li><a href="https://github.com/Azure-Samples/resources-java-deploy-using-arm-template-with-progress">Deploy resources with ARM templates (with progress)</a></li>
+</ul></td>
+  </tr>
+  <tr>
+    <td>Key Vault</td>
+    <td><ul style="list-style-type:circle">
+<li><a href="https://github.com/Azure-Samples/key-vault-java-manage-key-vaults">Manage key vaults</a></li>
+</ul></td>
+  </tr>
+  <tr>
+    <td>Batch</td>
+    <td><ul style="list-style-type:circle">
+<li><a href="https://github.com/Azure-Samples/batch-java-manage-batch-accounts">Manage batch accounts</a></li>
+</ul></td>
+  </tr>
+</table>
 
 # Download
 
 
-**1.0.0-beta2**
+**1.0.0-beta3**
 
-If you are using released builds from 1.0.0-beta2, add the following to your POM file:
+If you are using released builds from 1.0.0-beta3, add the following to your POM file:
 
 ```xml
 <dependency>
     <groupId>com.microsoft.azure</groupId>
     <artifactId>azure</artifactId>
-    <version>1.0.0-beta2</version>
+    <version>1.0.0-beta3</version>
 </dependency>
 ```
 
-or Gradle:
-
-    compile group: 'com.microsoft.azure', name: 'azure', version: '1.0.0-beta2'
-
-**Snapshots builds for this repo**
-
-If you are using snapshots builds for this repo, add the following repository and dependency to your POM file:
-
-```xml
-  <repositories>
-    <repository>
-      <id>ossrh</id>
-      <name>Sonatype Snapshots</name>
-      <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
-      <layout>default</layout>
-      <snapshots>
-        <enabled>true</enabled>
-        <updatePolicy>always</updatePolicy>
-      </snapshots>
-    </repository>
-  </repositories>
-```
-
-```xml
-<dependency>
-    <groupId>com.microsoft.azure</groupId>
-    <artifactId>azure</artifactId>
-    <version>1.0.0-SNAPSHOT</version>
-</dependency>
-```
-
-or Gradle:
-```groovy
-repositories {
-    maven { url "https://oss.sonatype.org/content/repositories/snapshots/" }
-    ....
-}
-```
-
-
-    compile group: 'com.microsoft.azure', name: 'azure', version: '1.0.0-SNAPSHOTS'
-
 #Pre-requisites
 
 - A Java Developer Kit (JDK), v 1.7 or later
@@ -166,6 +203,9 @@ repositories {
 
 
 ## Help
+
+If you are migrating your code to 1.0.0-beta3, you can use these notes for [preparing your code for 1.0.0-beta3 from 1.0.0-beta2](./notes/prepare-for-1.0.0-beta3.md).
+
 If you encounter any bugs with these libraries, please file issues via [Issues](https://github.com/Azure/azure-sdk-for-java/issues) or checkout [StackOverflow for Azure Java SDK](http://stackoverflow.com/questions/tagged/azure-java-sdk).
 
 #Contribute Code
@@ -187,6 +227,7 @@ If you would like to become an active contributor to this project please follow
 
 | Version           | SHA1                                                                                      | Remarks                                               |
 |-------------------|-------------------------------------------------------------------------------------------|-------------------------------------------------------|
+| 1.0.0-beta2       | [1.0.0-beta2](https://github.com/Azure/azure-sdk-for-java/tree/1.0.0-beta2)               | Tagged release for 1.0.0-beta2 version of Azure management libraries |
 | 1.0.0-beta1       | [1.0.0-beta1](https://github.com/Azure/azure-sdk-for-java/tree/1.0.0-beta1)               | Maintenance branch for AutoRest generated raw clients |
 | 1.0.0-beta1+fixes | [v1.0.0-beta1+fixes](https://github.com/Azure/azure-sdk-for-java/tree/v1.0.0-beta1+fixes) | Stable build for AutoRest generated raw clients       |
 | 0.9.x-SNAPSHOTS   | [0.9](https://github.com/Azure/azure-sdk-for-java/tree/0.9)                               | Maintenance branch for service management libraries   |

diff --git a/notes/prepare-for-1.0.0-beta3.md b/notes/prepare-for-1.0.0-beta3.md
@@ -0,0 +1,148 @@
+# Prepare for Azure Management Libraries for Java 1.0.0-beta3#
+
+Steps to migrate code that uses Azure Management Libraries for Java from beta 2 to beta 3 …
+
+> If this note missed any breaking changes, please open a pull request.
+
+# Replace Import Statement #
+
+<table>
+  <tr>
+    <th>Replace</th>
+    <th>With</th>
+    <th>Ref</th>
+  </tr>
+  <tr>
+    <td><code>import com.microsoft.azure.Azure</code></td>
+    <td><code>import com.microsoft.azure.management.Azure</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1144">#1144</a></td>
+  </tr>
+</table>
+
+# Change Method Names #
+
+<table>
+  <tr>
+    <th>From</th>
+    <th>To</th>
+    <th>Ref</th>
+  </tr>
+  <tr>
+    <td><code>Subnet.networkSecurityGroup()</code></td>
+    <td><code>Subnet.getNetworkSecurityGroup()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1140">#1140</a></td>
+  </tr>
+  <tr>
+    <td><code>Network.dsnServerIPs()</code></td>
+    <td><code>Network.dnsServerIps()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1140">#1140</a></td>
+  </tr>
+  <tr>
+    <td><code>NicIpConfiguration.publicIpAddress()</code></td>
+    <td><code>NicIpConfiguration.getPublicIpAddress()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1083">#1083</a></td>
+  </tr>
+  <tr>
+    <td><code>NicIpConfiguration.network()</code></td>
+    <td><code>NicIpConfiguration.getNetwork()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1083">#1083</a></td>
+  </tr>
+  <tr>
+    <td><code>NetworkInterface.networkSecurityGroup()</code></td>
+    <td><code>NetworkInterface.getNetworkSecurityGroup()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1065">#1065</a></td>
+  </tr>
+  <tr>
+    <td><code>NicIpConfiguration.privateIp()</code></td>
+    <td><code>NicIpConfiguration.privateIpAddress()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1055">#1055</a></td>
+  </tr>
+  <tr>
+    <td><code>VirtualMachine.primaryPublicIpAddress()</code></td>
+    <td><code>VirtualMachine.getPrimaryPublicIpAddress()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1090">#1090</a></td>
+  </tr>
+  <tr>
+    <td><code>StorageAccount.refreshKeys()</code></td>
+    <td><code>StorageAccount.getKeys()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1090">#1090</a></td>
+  </tr>
+  <tr>
+    <td><code>NetworkInterface.primaryNetwork()</code></td>
+    <td><code>NetworkInterface.getPrimaryNetwork()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1090">#1090</a></td>
+  </tr>
+</table>
+
+# Change Receiving Variable Type #
+
+<table>
+  <tr>
+    <th>From</th>
+    <th>To</th>
+    <th>For Method</th>
+    <th>Ref</th>
+  </tr>
+  <tr>
+    <td><code>List</code></td>
+    <td><code>Map</code></td>
+    <td><code>NetworkInterface.ipConfigurations()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1055">#1055</a></td>
+  </tr>
+  <tr>
+    <td><code>List</code></td>
+    <td><code>Map</code></td>
+    <td><code>VirtualMachine.resources()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1045">#1045</a></td>
+  </tr>
+  <tr>
+    <td><code>List</code></td>
+    <td><code>Map</code></td>
+    <td><code>NetworkSecurityGroup.securityRules()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/970">#970</a></td>
+  </tr>
+  <tr>
+    <td><code>List</code></td>
+    <td><code>Map</code></td>
+    <td><code>NetworkSecurityGroup.defaultSecurityRules()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/970">#970</a></td>
+  </tr>
+</table>
+
+# Drop Method Usage or Use Alternate #
+
+There are alternate ways to achieve the same thing:
+
+<table>
+  <tr>
+    <th>Drop Method</th>
+    <th>Use Alternate</th>
+    <th>Ref</th>
+  </tr>
+  <tr>
+    <td><code>NetworkInterface.primarySubnetId()</code></td>
+    <td><code>NetworkInterface.primaryIpConfiguration().subnetId()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1090">#1090</a></td>
+  </tr>
+  <tr>
+    <td><code>NicIpConfiguration.subnetId()</code></td>
+    <td>Use <code>NicIpConfiguration.subnetName()</code> for the name of the subnet, and <code>.networkId()</code> for its parent virtual network ID. Or simply call <code>.getNetwork()</code> for the actual associated Network instance and look up the subnet using <code>Network.subnets().get(subnetName)</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1090">#1090</a></td>
+  </tr>
+  <tr>
+    <td><code>NetworkInterface.primaryPublicIpAddress()</code></td>
+    <td><code>NetworkInterface.primaryIpConfiguration().getPublicIpAddress()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1090">#1090</a></td>
+  </tr>
+  <tr>
+    <td><code>StorageAccount.keys()</code></td>
+    <td><code>StorageAccount.getKeys()</code></td>
+    <td><a href="https://github.com/Azure/azure-sdk-for-java/pull/1090">#1090</a></td>
+  </tr>
+</table>
+
+# Add Property #
+
+Add another property <code>graphURL=https\://graph.windows.net/</code> to the experimental Azure Auth file [#1107](https://github.com/Azure/azure-sdk-for-java/pull/1107).
+
+