nacx requested changes on this pull request. Thanks for taking your time to write the docs @trevorflanagan. This is highly appreciated!
> + +-------------- + +## <a id="concepts"></a>Concepts + +The jclouds library wraps the [Dimension Data CloudControl API](https://docs.mcp-services.net/display/DEV/Welcome+to+the+CloudControl+documentation+portal). All operations are performed over SSL and authenticated using your Dimension Data CloudControl credentials. The API can be accessed directly over the Internet from any application that can send an HTTPS request and receive an HTTPS response. + + +## <a id="getting-started"></a>Getting Started + +Before you begin you will need to have a Dimension Data CloudControl account for your organization. The credentials will be used to authenticate against the API. + +The Dimension Data CloudControl provider supports [API version 2.4](https://docs.mcp-services.net/display/CCD/Understanding+API+v0.9+vs.+API+v2) and [MCP 2.0 datacenters](https://docs.mcp-services.net/display/CCD/Introduction+to+MCP+2.0+Data+Center+Locations) only. + +Upgrading to later versions is planned and in progress, see [JCLOUDS-1456](https://issues.apache.org/jira/browse/JCLOUDS-1456) and [JCLOUDS-1407](https://issues.apache.org/jira/browse/JCLOUDS-1407) for current progress. + Instead of linking to specific issues (which will become obsolete quite soon) you could add a generic message and point to a JIRA search on the `dimensiondata` label. > + +## <a id="concepts"></a>Concepts + +The jclouds library wraps the [Dimension Data CloudControl API](https://docs.mcp-services.net/display/DEV/Welcome+to+the+CloudControl+documentation+portal). All operations are performed over SSL and authenticated using your Dimension Data CloudControl credentials. The API can be accessed directly over the Internet from any application that can send an HTTPS request and receive an HTTPS response. + + +## <a id="getting-started"></a>Getting Started + +Before you begin you will need to have a Dimension Data CloudControl account for your organization. The credentials will be used to authenticate against the API. + +The Dimension Data CloudControl provider supports [API version 2.4](https://docs.mcp-services.net/display/CCD/Understanding+API+v0.9+vs.+API+v2) and [MCP 2.0 datacenters](https://docs.mcp-services.net/display/CCD/Introduction+to+MCP+2.0+Data+Center+Locations) only. + +Upgrading to later versions is planned and in progress, see [JCLOUDS-1456](https://issues.apache.org/jira/browse/JCLOUDS-1456) and [JCLOUDS-1407](https://issues.apache.org/jira/browse/JCLOUDS-1407) for current progress. + + +### Installation Remove this section contents and just point to the=jclouds [Install](https://jclouds.apache.org/start/install/) page. > +### Terms +Like any cloud provider, Dimension Data CloudControl has its own set of terms in cloud computing. To abstract this into jclouds' Compute interface, these terms were associated: + +- Node - a `Server` +- Image - both *user-uploaded* and *provided* `CustomerImage` and `OSImage` +- Location - `Geographic Region` equates to a jclouds Region (AU, NA, EU etc) and `Datacenter` equates to a jclouds Zone (NA9, NA12 etc). There is further information on the Geographic Regions [here](https://docs.mcp-services.net/display/CCD/Introduction+to+Geographic+Regions). +- Hardware - number of cores, RAM size and storage size for a given Image + +### Getting Started + +{% highlight java %} + ComputeService compute = ContextBuilder.newBuilder( "dimensiondata-cloudcontrol" ) + .credentials( "username", "password" ) + .buildView( ComputeServiceContext.class ) + .getComputeService(); +{% endhighlight %} AFAIK there is no `ComputeSerrvice` implementation yet. Does this work? > + +The Dimension Data CloudControl organization will be associated with one or more [MCP 2.0 Data Centers](https://docs.mcp-services.net/display/CCD/Introduction+to+MCP+2.0+Data+Center+Locations). A Data Center is a container for the assets that will be deployed and created by the jclouds Dimension Data CloudControl Provider. + +In jclouds terminology a Zone equates to a Data Center. + +The following code example shows you how to programmatically list Data Centers: + +{% highlight java %} + PagedIterable<Datacenter> datacenters = api.getInfrastructureApi().listDatacenters(); +{% endhighlight %} + +This responds with a paged result set containing the Data Centers visible to your organization. + +## <a id="how-to-deploy-a-network-domain"></a>How to: Deploy a Network Domain + +For more information on Network Domains see [here](https://docs.mcp-services.net/display/CCD/Introduction+to+Cloud+Network+Domains+and+VLANs) [minor] punctuation at the end. > +The following code example shows you how to programmatically list Data > Centers: + +{% highlight java %} + PagedIterable<Datacenter> datacenters = api.getInfrastructureApi().listDatacenters(); +{% endhighlight %} + +This responds with a paged result set containing the Data Centers visible to your organization. + +## <a id="how-to-deploy-a-network-domain"></a>How to: Deploy a Network Domain + +For more information on Network Domains see [here](https://docs.mcp-services.net/display/CCD/Introduction+to+Cloud+Network+Domains+and+VLANs) + +The code to deploy a network domain follows. + +{% highlight java %} + /* Remove indent from code snippets. The code appears indented in the code box and looks ugly. Apply this to all code boxes. > + +The code to deploy a network domain follows. + +{% highlight java %} + /* + * Deploy Network Domain to the Zone / Datacenter we wish to operate on. The response from this API is the Network Domain Identifier. + */ + String networkDomainId = api.getNetworkApi().deployNetworkDomain(AU9, "jclouds-example", "jclouds-example", "ESSENTIALS"); +{% endhighlight %} + +A Network Domain deployment is an asynchronous process. We need to wait for it to complete. The Dimension Data provider +has built in google guice predicates that will block execution and check that the Network Domain's State has moved from PENDING_ADD to NORMAL. + +Following is some example code that shows how the to use predicate suitable for asserting a Network Domain state has transitioned to the NORMAL state. The predicate uses the Network Domain Identifier we wish to check the state of. +{% highlight java %} + Injector injector = contextBuilder.buildInjector(); Don't do this. Instead use `context.utils().injector()` and if necessary explain how to build an `ApiContext< DimensionDataCloudControlApi>`. Users should never manually build the injector. > +{% highlight java %} + /* + * Deploy Network Domain to the Zone / Datacenter we wish to operate on. The response from this API is the Network Domain Identifier. + */ + String networkDomainId = api.getNetworkApi().deployNetworkDomain(AU9, "jclouds-example", "jclouds-example", "ESSENTIALS"); +{% endhighlight %} + +A Network Domain deployment is an asynchronous process. We need to wait for it to complete. The Dimension Data provider +has built in google guice predicates that will block execution and check that the Network Domain's State has moved from PENDING_ADD to NORMAL. + +Following is some example code that shows how the to use predicate suitable for asserting a Network Domain state has transitioned to the NORMAL state. The predicate uses the Network Domain Identifier we wish to check the state of. +{% highlight java %} + Injector injector = contextBuilder.buildInjector(); + Predicate<String> networkDomainNormalPredicate = injector.getInstance(Key.get(new TypeLiteral<Predicate<String>>() + { + }, Names.named("NETWORK_DOMAIN_NORMAL_PREDICATE"))); If this is going to be user-facing you'd probably want to expose that `Key` as a public constant in the code so they just have to do `injector.getInstance(NETWORK_DOMAIN_PREDICATE)`. > + +A Network Domain deployment is an asynchronous process. We need to wait for it to complete. The Dimension Data provider +has built in google guice predicates that will block execution and check that the Network Domain's State has moved from PENDING_ADD to NORMAL. + +Following is some example code that shows how the to use predicate suitable for asserting a Network Domain state has transitioned to the NORMAL state. The predicate uses the Network Domain Identifier we wish to check the state of. +{% highlight java %} + Injector injector = contextBuilder.buildInjector(); + Predicate<String> networkDomainNormalPredicate = injector.getInstance(Key.get(new TypeLiteral<Predicate<String>>() + { + }, Names.named("NETWORK_DOMAIN_NORMAL_PREDICATE"))); + networkDomainNormalPredicate.apply(networkDomainId); +{% endhighlight %} + +## <a id="how-to-deploy-a-vlan"></a>How to: Deploy a Vlan + +For more information on Vlans see [here](https://docs.mcp-services.net/display/CCD/Introduction+to+Cloud+Network+Domains+and+VLANs) Punctuation. > + +## <a id="how-to-deploy-a-network-domain"></a>How to: Deploy a Network Domain + +For more information on Network Domains see [here](https://docs.mcp-services.net/display/CCD/Introduction+to+Cloud+Network+Domains+and+VLANs) + +The code to deploy a network domain follows. + +{% highlight java %} + /* + * Deploy Network Domain to the Zone / Datacenter we wish to operate on. The response from this API is the Network Domain Identifier. + */ + String networkDomainId = api.getNetworkApi().deployNetworkDomain(AU9, "jclouds-example", "jclouds-example", "ESSENTIALS"); +{% endhighlight %} + +A Network Domain deployment is an asynchronous process. We need to wait for it to complete. The Dimension Data provider +has built in google guice predicates that will block execution and check that the Network Domain's State has moved from PENDING_ADD to NORMAL. Quote constants as code `PENDING_ADD` and `NORMAL` (apply elsewhere). > +{% endhighlight %} + +A Vlan deployment is an asynchronous process. We need to wait for it to complete. The Dimension Data provider has built in predicates that will block execution and check that the Vlan's State has moved from PENDING_ADD to NORMAL. + +Following is some example code that shows how the to use predicate suitable for asserting a Vlan state has transitioned to the NORMAL state. The predicate uses the Vlan Identifier we wish to check the state of. +{% highlight java %} + Injector injector = contextBuilder.buildInjector(); + Predicate<String> vlanNormalPredicate = injector.getInstance(Key.get(new TypeLiteral<Predicate<String>>() + { + }, Names.named("VLAN_NORMAL_PREDICATE"))); + vlanNormalPredicate.apply(vlanId); +{% endhighlight %} + +## <a id="how-to-list-available-os-images"></a>How to: List Os Images + +For more information on Os Images see [here](https://docs.mcp-services.net/display/CCD/Introduction+to+MCP+2.0+Data+Center+Locations#IntroductiontoMCP2.0DataCenterLocations-CloudImagesandServers) Punctuation (apply elsewhere). > + +Dimension Data CloudControl allows for Tags to be applied to assets. There are two parts to the tagging process, first a tag key needs to be created, second the tag key is applied to an asset. + +Create a tag key. We will use this to tag the assets that we create. +{% highlight java %} + String tagKeyId = api.getTagApi().createTagKey("jclouds", "owner of the asset", true, false); +{% endhighlight %} + +Follows is the sample code for applying a Tag to the Server. We use AssetType SERVER. Pass in the tagKeyId and a value that we want to associate, in this case jclouds. +{% highlight java %} + api.getTagApi().applyTags(serverId, "SERVER", Collections.singletonList(TagInfo.create(tagKeyId, "jclouds"))); +{% endhighlight %} + +The full set of AssetTypes are SERVER, NETWORK_DOMAIN, VLAN, CUSTOMER_IMAGE, PUBLIC_IP_BLOCK or ACCOUNT. + +## <a id="examples"></a>Examples: This is gonna become obsolete quickly. Remove the code examples here and link to the examples repo. -- You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub: https://github.com/jclouds/jclouds-site/pull/220#pullrequestreview-163243226
