In this post, we'll take a look at how to use Infracost with Terraform to gain greater visibility into your infrastructure costs and make cost control a shared responsibility across your organization.

First, let's talk about what Infracost is and how it works. Infracost is an open-source tool that generates cost estimates for your cloud resources by integrating with your infrastructure as code repository. It supports multiple cloud providers, including AWS, Azure, and GCP, and can be used with Terraform and soon with CloudFormation and Pulumi.

The most fascinating aspect here is that Infracost empowers developers to take the driver's seat in cloud cost control by providing them with real-time visibility into the costs of their resources and the ability to see the cost impact of changes before they are applied.
This gives developers the tools they need to identify high-cost resources and make adjustments to them, such as scaling down or deleting them, to reduce costs. Additionally, the ability to see cost savings opportunities and include cost estimates in their pull requests enables developers to make more informed decisions about which resources to create, modify or delete and share their cost-saving measures with other stakeholders.
With Infracost, developers can take ownership of their resources costs and take action to optimize them, and also, they can assist in the budgeting process and make sure that they are aligned with the organization's financial goals.
This way, Infracost can be a valuable tool that empowers developers to help with cost control, promoting a culture of cost awareness, and encouraging collaboration across the organization to optimize the cloud infrastructure costs.

A word about cost estimate reports

It is important to note that Infracost cost estimates are based on the standard public pricing provided by cloud providers such as AWS, GCP, or Azure and do not take into account any discounts that your project or organization may have.

However, even with standard public prices, Infracost can still provide a good estimate of your project's costs.

By using Infracost Cloud, the SaaS product that builds on top of the Infracost open-source tool, you can create custom price books that reflect any discounts you may have, resulting in more accurate cost estimates that align with the invoices you receive at the end of each month.

How to use

To use Infracost, you can easily install it by following the instructions provided on the Infracost website. Once installed, it can be integrated into any Terraform project.

In this post, we will be using a simple Terraform project as an example. You can access this example project on GitHub at the following link: https://github.com/devrealm/terraform-infracost

provider "aws" {
  region                      = "us-east-1"
  skip_credentials_validation = true
  skip_requesting_account_id  = true
  access_key                  = "mock_access_key"
  secret_key                  = "mock_secret_key"
}

resource "aws_instance" "ec2_instance_example" {
  ami           = "ami-0abe92d15a280b758"
  instance_type = "t2.micro"

  tags = {
    Name = "example-instance"
  }
}

resource "aws_s3_bucket" "s3_example_bucket" {
  bucket = "example-bucket"
}

resource "aws_db_instance" "rds_example" {
  engine                  = "postgres"
  instance_class          = "db.t2.micro"
  name                    = "example-db"
  allocated_storage       = 20
  storage_type            = "gp2"

  tags = {
    Name = "example-rds-instance"
  }
}

After installing Infracost, we can start getting cost estimates for our infrastructure:

$ cd terraform-infracost
$ infracost breakdown --path .

Evaluating Terraform directory at .
Project: devrealm/terraform-infracost

 Name                                                            Monthly Qty  Unit                    Monthly Cost

 aws_db_instance.rds_example
 ├─ Database instance (on-demand, Single-AZ, db.t2.micro)                730  hours                         $13.14
 └─ Storage (general purpose SSD, gp2)                                    20  GB                             $2.30

 aws_instance.ec2_instance_example
 ├─ Instance usage (Linux/UNIX, on-demand, t2.micro)                     730  hours                          $8.47
 └─ root_block_device
    └─ Storage (general purpose SSD, gp2)                                  8  GB                             $0.80

 aws_s3_bucket.s3_example_bucket
 └─ Standard
    ├─ Storage                                             Monthly cost depends on usage: $0.023 per GB
    ├─ PUT, COPY, POST, LIST requests                      Monthly cost depends on usage: $0.005 per 1k requests
    ├─ GET, SELECT, and all other requests                 Monthly cost depends on usage: $0.0004 per 1k requests
    ├─ Select data scanned                                 Monthly cost depends on usage: $0.002 per GB
    └─ Select data returned                                Monthly cost depends on usage: $0.0007 per GB

 OVERALL TOTAL                                                                                              $24.71
──────────────────────────────────
3 cloud resources were detected:
∙ 3 were estimated, all of which include usage-based costs, see https://infracost.io/usage-file

It's worth noting that for certain services that cost is based on usage, such as S3, Infracost may not be able to provide cost estimates by default. However, Infracost has a solution for this by allowing you to provide usage information.

In this example, you can create a file named infracost-usage.yml that contains the estimations of your S3 bucket usage. This file would look something like this:

# You can use this file to define resource usage estimates for Infracost to use when calculating
# the cost of usage-based resource, such as AWS Lambda.
# `infracost breakdown --usage-file infracost-usage.yml [other flags]`
# See https://infracost.io/usage-file/ for docs
version: 0.1
resource_usage:
  aws_s3_bucket.s3_example_bucket:
    standard: # Usages of S3 Standard:
      storage_gb: 10000 # Total storage in GB.
      monthly_tier_1_requests: 1000000 # Monthly PUT, COPY, POST, LIST requests (Tier 1).
      monthly_tier_2_requests: 100000 # Monthly GET, SELECT, and all other requests (Tier 2).
      monthly_select_data_scanned_gb: 10000 # Monthly data scanned by S3 Select in GB.
      monthly_select_data_returned_gb: 1000 # Monthly data returned by S3 Select in GB.

You can provide this usage file as an input to Infracost and it will use this information to generate cost estimates for your S3 bucket.

Now, with the usage information provided in the infracost-usage.yml file, Infracost will be able to calculate the cost for the S3 service and provide an estimate of, for example, $280.45.

$ infracost breakdown --path . --usage-file infracost-usage.yml
Project: devrealm/terraform-infracost

 Name                                                      Monthly Qty  Unit         Monthly Cost

 aws_db_instance.rds_example
 ├─ Database instance (on-demand, Single-AZ, db.t2.micro)          730  hours              $13.14
 └─ Storage (general purpose SSD, gp2)                              20  GB                  $2.30

 aws_instance.ec2_instance_example
 ├─ Instance usage (Linux/UNIX, on-demand, t2.micro)               730  hours               $8.47
 └─ root_block_device
    └─ Storage (general purpose SSD, gp2)                            8  GB                  $0.80

 aws_s3_bucket.s3_example_bucket
 └─ Standard
    ├─ Storage                                                  10,000  GB                $230.00
    ├─ PUT, COPY, POST, LIST requests                            1,000  1k requests         $5.00
    ├─ GET, SELECT, and all other requests                         100  1k requests         $0.04
    ├─ Select data scanned                                      10,000  GB                 $20.00
    └─ Select data returned                                      1,000  GB                  $0.70

 OVERALL TOTAL                                                                            $280.45
──────────────────────────────────
3 cloud resources were detected:
∙ 3 were estimated, all of which include usage-based costs, see https://infracost.io/usage-file

It's important to note that the usage file can be tailored to the specific resources in your project, and Infracost also provides a reference usage file that can serve as a guide for providing usage information for different supported resources.

Show cost estimate diff

Infracost also allows you to see the impact of changes to your resources on your cost estimates.

For instance, you can modify the EC2 and RDS instance types and see how it would affect the overall cost.

First, let's start by getting a baseline cost estimate by running the infracost breakdown command and save the output to a file.

infracost breakdown --path . --format json --out-file infracost-base.json --usage-file infracost-usage.ym

It's important to remember that when creating the baseline you need to include the usage file by passing the flag --usage-file infracost-usage.yml in the infracost breakdown command.

After that, we can make changes in the Terraform project by updating the EC2 and RDS instance types to "m5.4xlarge" and "m5.8xlarge" respectively. You can find the updated Terraform project in a new branch in the project's repository.

To see the impact of these changes on the cost estimate, we can then run the Infracost diff command to generate a new cost estimate report.

$ infracost diff --path . --compare-to infracost-base.json --usage-file infracost-usage.yml

Project: devrealm/terraform-infracost

~ aws_db_instance.rds_example
  +$2,066 ($15.44 → $2,081)

    ~ Database instance (on-demand, Single-AZ, db.t2.micro → db.m5.8xlarge)
      +$2,066 ($13.14 → $2,079)

~ aws_instance.ec2_instance_example
  +$552 ($9.27 → $561)

    ~ Instance usage (Linux/UNIX, on-demand, t2.micro → m5.4xlarge)
      +$552 ($8.47 → $561)

Monthly cost change for devrealm/terraform-infracost
Amount:  +$2,618 ($280 → $2,899)
Percent: +934%

──────────────────────────────────
Key: ~ changed, + added, - removed

3 cloud resources were detected:
∙ 3 were estimated, all of which include usage-based costs, see https://infracost.io/usage-file

As you can see, the cost for RDS service has increased dramatically from $13.14 to $2,079 and the cost for EC2 service has increased from $280 to $2,899.

With Infracost, you can also see the cost estimate difference as a comment on a pull request or a commit, which can be useful in a CI/CD pipeline. You can learn more about this feature by reading the Infracost documentation.

Infracost Cloud

Infracost Cloud is a SaaS product that builds on top of the Infracost open-source tool, providing an easy-to-use dashboard and detailed reports for controlling costs in one central location.

To set up Infracost Cloud, you can follow the instructions provided and link your Terraform project repository. Once setup is completed, you will have access to your repositories and their associated cost estimate reports.

For example, in the screenshot below, you can see the main screen of the devrealm/terraform-infracost repository, which shows a pull request to upgrade the EC2 and RDS instance types, and the resulting increase in costs.

By navigating to the "All estimates" tab, you can see the cost estimate report for the initial commit in the main branch.

Finally, by checking the "Pull requests" tab, you can view the cost estimate report for the PR and see the details of the difference compared to the main branch or the total cost in a tabular format.

In conclusion, Infracost is a powerful tool that allows developers to take a proactive approach to manage cloud infrastructure costs.
By providing real-time cost estimates and alerts, developers can identify and address cost issues before they become significant problems. This not only helps to keep costs under control but also promotes a culture of cost awareness and responsibility within development teams. By integrating Infracost into your development workflow, you can gain greater visibility and control over your cloud infrastructure costs, enabling you to make more informed decisions and optimize your resources.

To start using Infracost, you can visit their website at https://www.infracost.io and check their documentation.

Get in touch

Your feedback is appreciated, please leave a comment on the post to let me know what you think.

If you're ready to take the next step in cost-effective cloud management with Infracost and Terraform, reach out at george@devrealm.org or connect on LinkedIn at https://www.linkedin.com/in/georgevagenas/ to see how I can help.

Testing such integration with a proprietary or legacy system can be complex, if possible at all, since most of the time, the proprietary system is not based on an open-source protocol and mocking the internals of the system is not an option.

Examples of such proprietary or legacy systems are banking software and telephony systems.

To test such projects, you are only left with live tests, which means using the live system, sometimes the system in the production environment, to simulate use cases and check that your application behaves as expected.

But live testing shouldn't be an option at all. Here are some of the downsides of live testing

• they are not automated

• they cannot be run as part of a CI/CD pipeline

• they are error-prone

• they are time-consuming

PCAP Replay

Looking for any tools that can help here, I came across the excellent project Wiresham (https://github.com/abstracta/wiresham/) a simple TCP service mocking tool for replaying tcpdump or Wireshark captured service traffic.

You can check project details on how to set up Wiresham on your application.

The required tools are:

• tcpdump

• wiresham

Following are the steps needed to capture live traffic, prepare dump flows and set up replays in your test case.

Capture live traffic with tcpdump

To capture live traffic we need the external proprietary system and our application.

Some of the important things to consider on capturing live traffic:

1. Check which ports are involved. For some applications, ports might include signaling and media

2. Start tcpdump for each of the discovered ports. Make sure you define the proper network interface, for example, if traffic goes through VPN, start tcpdump on the VPN interface.

For example:
sudo tcpdump port 450 -i ppp0 -w jtapi_450.pcap

Dump flow files with wiresham

Use standalone wiresham to dump data from pcap to a simple flow file that later will be used in the integration test.

It is important to specify the ip address of the service that we want to mock using the "-a" option, this way wiresham can properly prepare the dump flow.
Using the "-a" option allows Wiresham to identify which tcp packets are coming from the mocked service, and prepare the flow accordingly - remember we need to mock the external service and have our application receive any request/response from the mocked service.

If for example the ip address of the server we need to mock is 10.100.26.31 we need to run the command:

java -jar ./wiresham-0.4.3-standalone.jar -d dump-450.yml -a 10.100.26.31 jtapi_450.pcap

-a (--server-address) ip address : When using a Wireshark generated JSON dump or PCAP file, this parameter specifies the IP address which identifies the service to be virtualized
...
-d (--dump-file) .yml file : File path to dump loaded flow config. The virtual service will not be started when this option is specified. This option makes sense when a Wireshark JSON file is used for config to dump a simplified and smaller file and then manually tune it if needed

The result of the operation will be yaml files that will be used in the test.

Integration test

To properly set up an integration test we need wiresham dependency to use the tools such as VirtualTcpService.

The test will have to instantiate as many VirtualTcpService tools as the number of flow files prepared earlier.

The VirtualTcpService tools need to be set with the proper port, flow file and started.

In the test, reference the mocked remote service using the localhost ip address and the service port.

Avaya Application Enablement Services Example

Avaya AES is one of the proprietary systems that are very complicated to mock and prepare tests for an application that uses JTAPI library to integrate with the service.

Using the tcpdump and wiresham project, we can capture live traffic and then prepare flows to be used in integration test cases for applications using JTAPI.

Following, you will see the steps needed how to capture JTAPI traffic and replay it in a test case.

Capture with tcpdump

AES traffic uses the following two ports

• TCP/450

• TCP/1050

To prepare the test we first need to start tcpdump capture and second start the JTAPI application and connect to AES server.

Use two different tcpdump process to capture AES real traffic

• sudo tcpdump port 450 -i ppp0 -w jtapi_450.pcap

• sudo tcpdump port 1050 -i ppp0 -w jtapi_1050.pcap

Depending on your needs, you can capture just the AES connection, register a station for events and capture events.

Dump flow files

Use standalone wiresham to dump data from pcap to simple flow file.

Make sure to specify the ip address of the Avaya AES server using the "-a" option, which in the example is 10.100.26.31.

• java -jar ./wiresham-0.4.3-standalone.jar -d dump-450.yml -a 10.100.26.31 jtapi_450.pcap

• java -jar ./wiresham-0.4.3-standalone.jar -d dump-1050.yml -a 10.100.26.31 jtapi_1050.pcap

The result of the operation will be two files:

• dump-450.yml

• dump-1050.yml

Prepare the test

We need to prepare the test with two instances of VirtualTcpService, set their port to 450 and 1050 and set the flow to the relevant files.

private VirtualTcpService service450 = new VirtualTcpService();
private VirtualTcpService service1050 = new VirtualTcpService();

@BeforeEach
public void setUp() throws Exception {
service450.setPort(450);
service450.setFlow(loadFlow("/dump-450.yml"));
service450.start();

service1050.setPort(1050);
service1050.setFlow(loadFlow("/dump-1050.yml"));
service1050.start();
}

The above setup is everything we need to have the test to mock the JTAPI link to Avaya AES.

Leave your comments and suggestions below

Because of its size and the SQL compatibility that the H2 database provides, it can be used as an embedded database instead of HSQLDB or other, and of course in the test suite of an application instead of using the DB used in production (for example MySQL, Postgres etc)

The H2 database can connect to any remote or local DB that supports JDBC for checking DB connection, checking or modify data etc. The html console is a very handy tool for all those cases.

Setup JDBC connection

We start by downloading the h2 standalone archive from https://h2database.com/html/main.html

Next we need to provide the JDBC driver for the DB server we want to connect.

For example, for MS SQL DB server, proceed to https://docs.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server?view=sql-server-2017 and download the version of JDBC driver you need for the SQL Server.

Create a folder drivers inside /h2 and place the download JDBC jar file there.

Now we need to tell H2 to load this JDBC jar in the classpath and make it available so we need to define the H2DRIVERS system variable.

export H2DRIVERS=/home/user/h2/drivers/mssql-jdbc-6.1.0.jre8.jar

You might want to have more JDBC jars in the classpath, for MySQL for example, in that case the H2DRIVERS will have to include all of them like this

export H2DRIVERS=/home/user/h2/drivers/mssql-jdbc-6.1.0.jre8.jar:/home/user/h2/drivers/mysql-connector-java-8.0.16.jar

Make sure you change the folder location from /home/user/h2 to the actual location in your machine.

The h2 folder will look like this

Next we can start h2. Head to bin folder and use the startup script for your OS (Windows → /bat or for Linux/Mac → .sh)

When the h2 start, the console will start at the console and now we can setup the connection details.

First thing is to pick the proper DB server from the dropdown menu, for MS SQL DB you need to pick Generic MS SQL Server 2005. By setting the server, the Driver class will be set for you automatically.

The only thing left for you to provide are:

• JDBC URL, for example jdbc:sqlserver:/SQLSERVER.company.com\INSTANCEID;databaseName=MyDB

• Username

• Password

The Login screen will look like this:

Now press Connect and you are in!!!

Bonus, allow web connections from remote hosts

By default H2 database does not allow connections from other machines when starting the H2 Console. So if you deploy and start H2 on a remote server, lets say in a dev environment, you won't be able to reach the H2 Console unless you instruct H2 to allow connections from remote hosts.

Remote access can be enabled using the command line options -webAllowOthers

To use this option run H2 like this

./h2.sh -webAllowOthers

This will allow web connection to H2 Console from remote hosts.

You can check more details about remote access here https://h2database.com/html/advanced.html?highlight=webAllowOthers&search=webAllowOth#remote_access

From the abstract of RFC3263:

• The Session Initiation Protocol (SIP) uses DNS procedures to allow a client to resolve a SIP Uniform
• Resource Identifier (URI) into the IP address, port, and transport protocol of the next hop to contact.
• It also uses DNS to allow a server to send a response to a backup client if the primary client has failed.

The document here describes those DNS procedures in detail.

When it comes to implement the proposed guidelines from RFC3263 in order to locate SIP server, the specification doesn’t seem to cover enough all the possible situations, specially for SIPS URI, and that is why we should consider to change some points there.

The purpose of this post is, first to indicate which points of the proposed RFC3263 mechanisms could create problems when it comes to resolve the transport for SIPS URIs and how these points should be changed by applying some rules on the results of the DNS query. Second this post provides what is the minimum DNS configuration for SIP, that is the minimum required NAPTR, SRV and A records according to the RFC3263.

1. RFC3263 misconceptions when it comes to transport resolution

The proposed mechanism from the specification for the transport resolution, suggest to have NAPTR query first and if this doesn’t return any results to issue a SRV query. At this point the the specification fails to provide clear directions on how to choose the transport when the URI under question is a SIPS URI.

We should consider to change the way the transport resolution mechanism have to be done keeping in mind the RFC5630 “The Use of the SIPS URI Scheme in the Session Initiation Protocol (SIP)” guidelines.

So as said before RFC3263 states that if the NATPR query returns no records, an SRV query should be performed and if that query returns any results that contains transports that the client can support, then the client can choose any of the results:

• A particular transport is supported if the query is successful. The client MAY use any transport protocol it desires which is supported by the server.

The “..use any transport protocol it desires which is supported by the server.” creates a confusion and problems when it comes to SIPS URIs. The SRV query results should be examined and some rules should be applied before we choose the transport.

Another point of conflict coming from RFC3263 for the transport resolution, is in the case where port is available in the URI. The specification states :

• if no transport protocol is specified, and the TARGET is not numeric, but an explicit port is provided, the client SHOULD use UDP for a SIP URI, and TCP for a SIPS URI.

This should be “TLS for a SIPS URI”

2. SIPS URI clarifications from the RFC5630 “The Use of the SIPS URI Scheme in the Session Initiation Protocol (SIP)”

RFC5630 purpose is to clarify the use of SIPS URI.

• The meaning and usage of the SIPS URI scheme and of Transport Layer Security (TLS) RFC5246 are underspecified in SIP RFC3261 and have been a source of confusion for implementers. This document provides clarifications and guidelines concerning the use of the SIPS URI scheme in the Session Initiation Protocol(SIP). It also makes normative changes to SIP (including both RFC3261 and RFC3608).

RFC5630 [3.1.3 – Using TLS with SIP Instead of SIPS] defines two uses of TLS, one with SIPS URI, and one with SIP URI. As it states SIPS URI should be treated as “TLS-only” requests, while using TLS with SIP URI should be treated as “best-effort TLS”.Taken from there, we should further enhance RFC3263 guidelines by taking into account RFC5630.SRV records of a DNS server should be clear of what they want to provide.

So if one would like to use the “best-effort TLS” approach this DNS SRV record should be included:

• _sip._tls.example.com. 43200 IN SRV 0 0 5060 sipserver1.example.com.

And if the client supports TLS, then TLS should be the chosen transport.

If the SIP server should follow the “TLS only” approach, then one of the following SRV records should be included (or both to support all possible queries) :

• _sips._tcp.example.com. 43200 IN SRV 0 0 5060 sipserver1.example.com.

OR

• _sips._tls.example.com. 43200 IN SRV 0 0 5060 sipserver1.example.com.

And the client will have to go with the TLS transport.

Of course, a server could provide both and so to give the ability to the client even if using SIP URI to go with a TLS transport if available.

3. How the DNS NAPTR results should be treated

When it comes to the NAPTR lookup, RFC3263 proposed mechanism to resolve transport is sufficient and the guidelines for SIP and SIPS URIs are clear enough:

• If a SIPS URI is given, discard any service that do not contain “SIPS” as the protocol in the service field. That conforms with the RFC5630 that SIPS URI should be treated as “TLS only”
• If a SIP URI is given, the client should retain records with “SIPS” as the protocol, if the client supports TLS. Again this conforms to the RFC5630 for “best-effort TLS” - Results should be processed according to the order of each record and the first one should be picked up to set the transport - If the result contain “SIPS” as a service protocol, the transport should be set to TLS
• If the result contain “D2T” as a service protocol, the transport should be set to TCP
• If the result contain “D2U” as a service protocol, the transport should be set UDP
• The “SIPS” service should be the preferred if the client can support it.

4. How the DNS SRV results should be treated

If the NAPTR lookup returns no results, a DNS SRV query should be done.

Here we need to clarify and change how the DNS results should be treated for a given request when transport is to be discovered, given the fact that the client supports TCP, UDP and TLS.

The statement from RFC5623 that the client should “use any transport protocol it desires which is supported by the server” is not enough to make a clear decision for the transport and further process of the result should be done using some rules.

For example, a SIP Registrar may provide the following SRV record for SIPS URI:

• _sips._tcp.example.com. 86400 IN SRV 0 0 5061 sipserver1.example.com.

If the client is to pick the TCP transport as is, then this will fail because the TCP connector wont be able to establish a connection with the TLS connector on the other side. In this example, the client should treat _sips._tcp result as “TLS only” and choose TLS as transport.

Since the DNS SRV records defined for a SIP server may vary from one application to the other, the client should collect all the results of a DNS SRV lookup, and then apply the following rules:

• Lookup for a SIP URI- SRV Record Results: [ _sip._tls, _sip._tcp, _sip._udp] => The _sip._tls should interpreted as “best-effort TLS” and the client should choose TLS as transport if available, otherwise ANY available transport
• SRV Record Results: [_sip._tcp, _sip._udp] => Client should choose ANY of the two results as long as they are available
• SRV Record Results: [_sip._tcp] => Client should choose TCP as transport
• SRV Record Results: [_sip._udp] => Client should choose UDP as transport
• Lookup for a SIPS URI- SRV Record Results: [_sips._tcp, any others] => Should be treated as “TLS only” approach and the client should set TLS as transport
• SRV Record Results: [_sips._tls, any others] => Should be treated as _sips._tcp, that is “TLS only” and the client should set TLS as transport

Of course if an SRV lookup doesn’t returns any result, the regular approach should be followed, that is to pick the default transport for the given URI.

• TLS for SIPS URI
• UDP for SIP URI OR
• TCP for SIP URI if UDP is not available

Should there be a preference between TCP and UDP?

5. DNS NAPTR required records

According to RFC3263 4.1, the minimum required NAPTR records a SIP proxy, redirect server, or registrar should have, if it comes to be resolved through a DNS lookup, are the following:

• example.com. IN NAPTR 50 50 “s” “SIPS+D2T” “” _sips._tcp.example.com.
• example.com. IN NAPTR 90 50 “s” “SIP+D2T” “” _sip._tcp.example.com
• example.com. IN NAPTR 100 50 “s” “SIP+D2U” “” sip._udp.example.com.

From RFC3263:

• If a SIP proxy, redirect server, or registrar is to be contacted through the lookup of NAPTR records, there MUST be at least three records – one with a “SIP+D2T” service field, one with a “SIP+D2U” service field, and one with a “SIPS+D2T” service field. The records with SIPS as the protocol in the service field SHOULD be preferred (i.e., have a lower value of the order field) above records with SIP as the protocol in the service field. A record with a “SIPS+D2U” service field SHOULD NOT be placed into the DNS, since it is not possible to use TLS over UDP.

Of course Domain, TTL, Priority, Preference, Port and FQDN of the the record should be set according to the application/needs.

6. DNS SRV required records

Accordingly, the minimum DNS SRV records that should be defined are:

• _sip._udp.example.com. 86400 IN SRV 0 0 5060 sipserver1.example.com.
• _sip._tcp.example.com. 86400 IN SRV 0 0 5060 sipserver1.example.com.
• _sips._tcp.example.com. 86400 IN SRV 0 0 5061 sipserver1.example.com.

So in the above example for SIP URIs and UDP or TCP transport, the request will be routed using port 5060 to the sipserver1.example.com. For secure SIPS URIs, the 5061 port should be used and the same server.

Of course Domain, TTL, Priority, Weight, Port and FQDN of the the record should be set according to the application/needs.

7. DNS A Records

Finally the DNS zone configuration should contain an A record for the domain:

• sipserver1.example.com. 86400 IN A 10.0.0.21

That will be used to resolve the FQDN of servers to an IP Address.

8. A complete DNS Zone configuration file

Here is an example of a complete DNS Zone configuration for the example.com domain.

$TTL 1800

@ IN SOA ns1.example.com. root.example.com. (

                   2012030101 ; serial#

                   1800            ; refresh, seconds

                   1800            ; retry, seconds

                   1800            ; expire, seconds

                   1800 )          ; minimum TTL, seconds

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; DNS Servers for ‘example.com’

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; NS record for example.com

; server: sipserver1.example.com

;

example.com. IN NS sipserver1.example.com.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Call Routing for SIP domain ‘example.com’

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; NAPTR record for SIPS TCP example.com

; priority: 2 weight: 0

; protocol: “SIPS+D2T” regex: “” uri: _sips._tcp.example.com

;

example.com. IN NAPTR 2 0 “s” “SIPS+D2T” “” _sips._tcp.example.com.

; NAPTR record for SIP TCP example.com

; priority: 2 weight: 0

; protocol: “SIP+D2T” regex: “” uri: _sip._tcp.example.com

;

example.com. IN NAPTR 2 0 “s” “SIP+D2T” “” _sip._tcp.example.com.

; NAPTR record for SIP UDP example.com

; priority: 2 weight: 0

; protocol: “SIP+D2U” regex: “” uri: _sip._udp.example.com

;

example.com. IN NAPTR 2 0 “s” “SIP+D2U” “” _sip._udp.example.com.

; SRV record for domain SIP TCP example.com

; priority: 1 weight: 0 port: 5060 server: sipserver1.example.com

;

_sip._tcp.example.com. IN SRV 1 0 5060 sipserver1.example.com.

; SRV record for domain SIP UDP example.com

; priority: 1 weight: 0 port: 5060 server: sipserver1.example.com

;

_sip._udp.example.com. IN SRV 1 0 5060 sipserver1.example.com.

; SRV record for domain SIP TLS example.com

; priority: 1 weight: 0 port: 5061 server: sipserver1.example.com

;

_sip._tls.example.com. IN SRV 1 0 5061 sipserver1.example.com.

; SRV record for domain SIPS TCP example.com

; priority: 1 weight: 0 port: 5061 server: sipserver1.example.com

;

_sips._tcp.example.com. IN SRV 1 0 5061 sipserver1.example.com.

; SRV record for domain SIPS TLS example.com

; priority: 1 weight: 0 port: 5061 server: sipserver1.example.com

;

_sips._tls.example.com. IN SRV 1 0 5061 sipserver1.example.com.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; IP Addresses

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; A record for sipserver1.example.com

;

sipserver1.example.com. IN A 192.168.1.207

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

9. How to test DNS configurations

In order to test A records, a simple ping would be enough. If the command ping sipserver1.example.com would result some replies, then A record configuration is okTo test SRV records, for Linux use dig command and for Windows use nslookup.

• Linux example: dig _sips._tcp.example.com SRV should result the IP Address and port of the server for SIPS TLS
• Windows example: use nslookup, then set querytype=SRV and then type the SRV record you wish, for example _sips._tcp.example.com. Should result the IP Address and port for SIPS TLS

Also, in order to check NAPTR records again use Linux dig.

For Windows i am not aware of a program that could be used to check NAPTR records, as nslookup doesn’t support this type of records (tested on Windows XP and Windows 7)

Linux example: dig example.com NAPTR will result with the available NAPTR records on the DNS server

10. Links / Resources

• RFC3263 http://www.ietf.org/rfc/rfc3263.txt
• RFC5630 http://tools.ietf.org/html/rfc5630
• SIP.EDU – DNS Configuration http://mit.edu/sip/sip.edu/dns.shtml
• Locating SIP Servers Blog by Binod – http://weblogs.java.net/blog/binod/archive/2008/02/using_dns_serve.html#comment-822520

Also please note that this article builds upon the previous articles JTapi Overview and JTapi hands-on, part I.

Prerequisites for the source code

In the Resources section of this articles you can find the source code for the examples. In order to compile and run the source code you need the JTapi library in your classpath and of course a PBX equipped with the appropriate JTAPI software services. For any help please leave a comment.

Use case

For the concepts and theories to be more easy to grasp, I will start by providing a specific use case to work with.

• Given that we have a PBX with JTapi services in place, we need to develop an application that will provide users with a list of telephone numbers to dial automatically using their PC; that is no manual dialling using their telephone set.

For this we need to develop a library which will be the connector between the application and the JTapi enabled PBX. The purpose of this library will be to create calls on behalf of the users and deliver the calls to their telephone set. So for the rest of the article I will provide the necessary theory and examples with source code to develop such a library.

First will have some theory in order to get the basics of Call and Connection interface, since these two interfaces are the fundamentals in the application we want to develop.

The Call interface

The Call object represents a telephone call, the information flowing between the service provider and the call participants. A telephone call comprises a Call object and zero or more connections. In a two-party call scenario, a telephone call has one Call object and two connections. A conference call is three or more connections associated with one Call object.

In order to create a Call, an idle call object is instantiated using Provider.createCall(). Having the idle call object in place, the application must specify the originating Terminal (physical endpoint) and the originating Address (logical endpoint) of that Terminal (in the case that a Terminal has multiple telephone numbers on it). Next the application should provide the destination telephone number as a string. Two Connection objects are returned from the Call.connect() method, representing the originating and destination ends of the telephone call.

Call States

A Call, like other Jtapi objects, has a state which is obtained via the Call.getState() method. This state describes the current progress of a telephone call, where is it in its life cycle, and how many Connections exist on the Call. The Call state may be one of three values: Call.IDLE, Call.ACTIVE, or Call.INVALID. Here is a description of each state:

• Call.IDLE: This is the initial state for all Calls. In this state, the Call has zero Connections, that is Call.getConnections() must return null.
• Call.ACTIVE: A Call with some current ongoing activity is in this state. Calls with one or more associated Connections must be in this state. If a Call is in this state, the Call.getConnections() method must return an array of size at least one.
• Call.INVALID: This is the final state for all Calls. Call objects which lose all of their Connections objects (via a transition of the Connection object into the Connection.DISCONNECTED state) moves into this state. Calls in this state have zero Connections and these Call objects may not be used for any future action. In this state, the Call.getConnections() must return null.

Note: The Connection states mentioned above will be discussed later in this article.

Call State Transitions

The possible Call state transitions are given in the diagram below:

Calls and Connections

A Call object maintain a list of the Connections on that Call. Applications obtain an array of Connections associated with the Call via the _Call.getConnections()_ method. A Call object retains a reference to a Connection only if it is not in the Connection.DISCONNECTED state. Therefore, if a Call object has a reference to a Connection, then that Connection must not be in the Connection.DISCONNECTED state. When a Connection moves into the Connection.DISCONNECTED state (e.g. when a party hangs up), the Call loses its reference to that Connection which is no longer reported via the _Call.getConnections()_ method.

Connection interface

A Connection represents a link (i.e. an association) between a Call object and an Address object.

The purpose of a Connection object is to describe the relationship between a Call object and an Address object. A Connection object exists if the Address is a part of the telephone call. Applications use the _Connection.getCall()_ and _Connection.getAddress()_ methods to obtain the Call and Address associated with this Connection, respectively.

Connection States

A connection can be in one of the states mentioned below and here is a description of each Connection state in real-world terms. These real-world descriptions have no bearing on the specifications of methods, they only serve to provide a more intuitive understanding of what is going on. Several methods in this specification state pre-conditions based upon the state of the Connection (for example see Connection.disconnect() method below)

• Connection.IDLE: This state is the initial state for all new Connections. Connections which are in the Connection.IDLE state are not actively part of a telephone call, yet their references to the Call and Address objects are valid. Connections typically do not stay in the Connection.IDLE state for long, quickly transitioning to other states.
• Connection.DISCONNECTED: This state implies it is no longer part of the telephone call, although its references to Call and Address still remain valid. A Connection in this state is interpreted as once previously belonging to this telephone call.
• Connection.INPROGRESS: This state implies that the Connection, which represents the destination end of a telephone call, is in the process of contacting the destination side. Under certain circumstances, the Connection may not progress beyond this state.
• Connection.ALERTING: This state implies that the Address is being notified of an incoming call.
• Connection.CONNECTED: This state implies that a Connection and its Address is actively part of a telephone call. In common terms, two people talking to one another this call is represented by two Connections in the Connection.CONNECTED state.
• Connection.UNKNOWN: This state implies that the implementation is unable to determine the current state of the Connection. Typically, methods are invalid on Connections which are in this state. Connections may move in and out of the Connection.UNKNOWN state at any time.
• Connection.FAILED: This state indicates that a Connection to that end of the call has failed for some reason. One reason why a Connection would be in the Connection.FAILED state is because the party was busy.

Connection State Transition

With these loose, real-world meanings in the back of one’s mind, the Connection class defines a finite-state diagram which describes the allowable Connection state transitions. This finite-state diagram must be guaranteed by the implementation. Each method which causes a change in a Connection state must be consistent with this state diagram. This finite state diagram is below:

Note there is a general left-to-right progression of the state transitions. A Connection object may transition into and out of the Connection.UNKNOWN state at any time (hence, the asterisk qualifier next to its bidirectional transition arrow).

Connection.disconnect() method

In terms of controlling a call, an important method of the Connection interface is the Connection.disconnect() method. This method drops an entire Connection from a telephone call. The result of this method is to move the Connection object into the Connection.DISCONNECTED state.
This method drops a Connection from an active telephone call and the Connection’s Address is no longer associated with the telephone call. Important to notice is that this method does not necessarily drop the entire telephone call, only the particular Connection on the telephone call. The method provides the ability to disconnect a specific party from a telephone call, which is especially useful in telephone calls consisting of three or more parties. For example on a three party conference call, if one of the parties invoke the _Connection.disconnect()_ method, then this party leaves the conference call, but the two parties left continue the call. Invoking this method may result in the entire telephone call being dropped though, which is a permitted outcome for this method. In that case, the appropriate events are delivered to the application, indicating that more than just a single Connection has been dropped from the telephone call.

This method returns successfully only after the Connection has been disconnected from the telephone call and has transitioned into the Connection.DISCONNECTED. Note that this method waits (i.e. the invocating thread blocks) until either the Connection is actually disconnected from the telephone call or an error is detected and an exception thrown.

Additional Connections may be dropped indirectly as a result of this method. For example, dropping the destination Connection of a two-party Call may result in the entire telephone call being dropped. It is up to the implementation to determine which Connections are dropped as a result of this method. Implementations should not, however, drop additional Connections if it does not reflect the natural response of the underlying telephone hardware.

Dropping additional Connections implies that their TerminalConnections are dropped as well. Also, if all of the Connections on a telephone call are dropped as a result of this method, the Call will move into the Call.INVALID state.

Be aware that the Connection object must be in one of several states in order for this method to be successfully invoked. These allowable states are: Connection.CONNECTED, Connection.ALERTING, Connection.INPROGRESS, or Connection.FAILED. If the Connection is not in one of these allowable states when this method is invoked, this method throws InvalidStateException. Having the Connection in one of the allowable states does not guarantee a successful invocation of this method.

Next will be discussed the structure of the project will be used for the library we need to implement the application in question.

Project Structure

The project has a bootstrap class, the ProviderService class, that provides the Jtapi Provider for the rest of the classes to use. This is convenient to have since several other classes can access the Provider (to retrieve resources, create calls etc.) without the need for each class to instantiate its own Provider object.
Next is the JTapiMakeCall class that is responsible to create and handle calls and side by side the CallTools class that provides useful information on the console about the progress of a call.

Even though this is a simple application, later can be used as a tool to create calls.

Bootstrap

As usual, the kick off of any JTapi project is the instantiation of JtapiPeer and Provider, and here is exactly that. So below is the ProviderService class that will make available the Provider to the rest of the project.

import javax.telephony.JtapiPeer;
import javax.telephony.JtapiPeerFactory;
import javax.telephony.JtapiPeerUnavailableException;
import javax.telephony.Provider;

public class ProviderService {
private static ProviderService instance;
private static Provider provider;

private ProviderService () {  
    bootStrap();  
}  

public static Provider getProvider () {  
    if (instance == null) {  
        instance = new ProviderService();  
    }  
    return provider;  
}  

private void bootStrap () {  
    try {  
        JtapiPeer peer = JtapiPeerFactory.getJtapiPeer("");  
        String\[\] myServices = peer.getServices();  
        String providerString = myServices\[0\] + ";login=user;passwd=passwd";  
        provider = peer.getProvider(providerString);  
    } catch (JtapiPeerUnavailableException e) {  
        e.printStackTrace();  
    }  
}  

}

Having the Provider available for the rest of the project, we are ready to move on the rest of the classes.

JTapiMakeCall Class

The JTapiMakeCall class consists of 4 methods.

• Call dial(String origAddrStr, String dialoutNumber): Accepts two strings, the original address and the dialout number to be called. The method will create the call object and will connect the original address with the number requested. Note: Be aware that the original address must be in the Provider’s domain but the same is not true for the dialout number. That is, the original address must be an extension of the PBX that is handled by the Provider while the dialout number could be any external number or an extension of the PBX also.
• void disconnect(Call call): If you noticed before, the dial method returns a Call object so any other method can work on this object. So the disconnect method accepts a Call object and terminates all the connections of call, if they are eligible for disconnect. As said earlier, a connection should be in one of the allowed states in order to be disconnected.
• Provider getProvider(): Will retrieve the Provider from the ProviderService class and make it available to the rest of the class.
• void shutdownProvider(): Will shut down the Provider when needed

Following is the source code of the JTapiMakeCall class:

package org.devrealm.jtapitutorial2.jtapimakecall;

import javax.telephony.Address;
import javax.telephony.Call;
import javax.telephony.Connection;
import javax.telephony.InvalidArgumentException;
import javax.telephony.InvalidPartyException;
import javax.telephony.InvalidStateException;
import javax.telephony.MethodNotSupportedException;
import javax.telephony.PrivilegeViolationException;
import javax.telephony.Provider;
import javax.telephony.ResourceUnavailableException;
import javax.telephony.Terminal;

import org.devrealm.jtapitutorial2.bootstrap.ProviderService;

public class JTapiMakeCall {
private static Provider provider;

public static Call dial (String origAddrStr, String dialoutNumber) {  
    Provider provider = JTapiMakeCall.getProvider();  
    Call call = null;  
    try {  
        Address myAddr = provider.getAddress(origAddrStr);  
        Terminal myTerm = myAddr.getTerminals()\[0\];  
        System.out.println("Calling from: " + origAddrStr + " to: " + dialoutNumber);  
        call = provider.createCall();  
        call.connect(myTerm, myAddr, dialoutNumber);  
    } catch (InvalidArgumentException e) {  
        e.printStackTrace();  
    } catch (ResourceUnavailableException e) {  
        e.printStackTrace();  
    } catch (InvalidStateException e) {  
        e.printStackTrace();  
    } catch (PrivilegeViolationException e) {  
        e.printStackTrace();  
    } catch (MethodNotSupportedException e) {  
        e.printStackTrace();  
    } catch (InvalidPartyException e) {  
        e.printStackTrace();  
    }  
    return call;  
}  

public static void disconnect (Call call) {  
    Connection\[\] connections = call.getConnections();  
    for (Connection connection : connections) {  
        //disconnect here  
    }  
}  

}

CallTools class

This class provides some methods to get useful information about a call.

The methods it provides are the following:

• void inspect(Call call): Using this method we can retrieve information about the connectios, addresses, call state etc. of a call object
• String connStateToString(int code): This method converts the integer code of a connection state to a string

Following is the source code of the CallTools class:

package org.devrealm.jtapitutorial2.dialout;

import javax.telephony.Call;

import org.devrealm.jtapitutorial2.jtapicalltools.CallTools;
import org.devrealm.jtapitutorial2.jtapimakecall.JTapiMakeCall;

public class Dialout {
public static void main (String[] args) {
String origAddrStr = "1234";
String dialoutNumber = "00123456789";
// Optionally you can accept the original address and dialout number from the command prompt
// String origAddrStr = args[0];
// String dialoutNumber = args[1];
Call call = JTapiMakeCall.dial(origAddrStr, dialoutNumber);
CallTools.inspect(call);
try {
Thread.sleep(10000);
} catch (InterruptedException e) {
e.printStackTrace();
}
System.out.println("Disconnect Call");
JTapiMakeCall.disconnect(call);
System.out.println("...............");
CallTools.inspect(call);
JTapiMakeCall.shutdownProvider();
}
}

Conclusion

The Call and Connection interface are straight forward and easy to work with and the documentation provided is well written. Using these two interfaces we can easily integrate an application with a PBX and give a production boost to a call centre. Going back to the use case defined at the begining of the article, the connector for the auto-dial functionality and integration with the PBX is ready to use. Of course that kind of application needs a lot more to be complete but this library is one of the most, if not the most, important part of the application. What is left to see is how we can answer, transfer, conference and observe calls so we can give a call centre with full set of automatic tools to handle both incoming and outgoing calls. Specially the observers that the JTapi API provides are useful to implement applications that observe addresses, terminals or calls for incoming traffic and captures details of the caller that can be used to popup the agent's desktop with the caller details. Finally please share any comment or idea derived from this article since that's the driving power of thought and any effort made here.

Resources

• JTapi Overview(https://blog.devrealm.org/2009/03/26/jtapi-overview/)
• JTapi hands-on, part I(https://blog.devrealm.org/2009/04/05/jtapi-hands-on-part-i/)

In the first article there was an introduction to the basic interfaces of JTAPI, that is JtapiPeer, Provider, Address, Terminal, Call and Connection. These are the basis on which we will built upon and continue in this article.

Starting from this article, I will leave the plain theory behind, and I will delve into the Jtapi objects using code examples. Off course, each code snippet, will be supported by the appropriate theory in order to elaborate and deeply analyze each object.

This iteration will concentrate on the JTapiPeer and Provider interfaces, and will present the way can be used to further inside an application using two example classes. The first one ProviderService mainly shows how to use JtapiPeer in order to instantiate and supply the Provider object for the second class JTapiDiscovery which purpose is just to discover the Addresses and Terminals from the Provider’s domain.

Prerequisites for the source code

In the Resources section of this articles you can find the source code from the examples. In order to compile and run the source code you need the JTapi library in your classpath and of course a PBX equipped with the appropriate JTAPI software services. Most of the PBX vendors provides for free the JTapi library implementation for their platform. For any help please leave a comment.

ProviderService: A useful helper class for the rest of the tutorial(s)

Given that the instantiation of a Provider, is the first step for any application, i decided to create a helper class ProviderService that will be used for the rest of the tutorial in order to retrieve the Provider from the JTapiPeer.

The ProviderService class follows:

package org.devrealm.jtapitutorial.bootstrap;

import javax.telephony.JtapiPeer;
import javax.telephony.JtapiPeerFactory;
import javax.telephony.JtapiPeerUnavailableException;
import javax.telephony.Provider;

public class ProviderService {
private static ProviderService instance;
private static Provider provider;

private ProviderService () {
bootStrap();
}

public static Provider getProvider () {
if (instance == null) {
instance = new ProviderService();
}
return provider;
}

private void bootStrap () {
try {
JtapiPeer peer = JtapiPeerFactory.getJtapiPeer("");
String[] myServices = peer.getServices();
String providerString = myServices[0] + ";login=user;passwd=passwd";
provider = peer.getProvider(providerString);
} catch (JtapiPeerUnavailableException e) {
e.printStackTrace();
}
}
}

The ProviderService is a helper class that implements the Singleton pattern(see Resources for more). The class supply a public static method getProvider that returns a Provider object to any other class request it.

Besides the usual singleton stuff, this class presents the method _bootStrap()_. Using this method, the class creates the Provider object and make it available.

Recall from the previous article, the JTapiPeer interface represents a vendor’s particular implementation of the Java Telephony API. So the first thing this class is doing is to retrieve an instance of the the JTapiPeer using the static method of the JtapiPeerFactory, JtapiPeerFactory.getJtapiPeer("") as you can see at line 19. Having a JTapiPeer instance in place, the bootStrap method, fetches all the available services this peer can provide.

• Depending on the vendor’s implementation of this interface, more than one service can be obtained if for example the telephony software-entity is connected to more than one telephony subsystems (e.g. a JTapi service/server connected to two PBX will result in two services).

The next step is to create the providerString, which will include the service in question, the username and password for the JTapi service user. Having the providerString in hand, we go on and request the Provider from the JTapiPeer with the method peer.getProvider(provideString).

Important things to remember from this class:

• Using the _JtapiPeerFactory.getJtapiPeer("");_ we retrieve the vendor’s implementation of the Java Telephony API.

• Having in hand the JtapiPeer, we construct the providerString which consists of the Jtapi service (most of the times will be only one), the user name and password for this service.

• From the JtapiPeer object we retrieve the Provider object using _Provider provider = peer.getProvider(providerString);_

Bare in mind that the above three simple steps are the foundation in order to initialize all the Java Telephony applications.

Next we move on the JTapiDiscovery class where the Provider is getting into action.

JTapiDiscovery: Provider in action

One of the things any JTapi application is supposed to do is first retrieve all available addresses and terminals (or otherwise all the requested addresses and terminals) and maybe place them in a storage area in order to be used later from the rest of the application’s logic. This is exactly what the next class, JTapiDiscovery is doing.

The JTapiDiscovery class follows:

package org.devrealm.jtapitutorial.discovery;

import javax.telephony.Address;
import javax.telephony.Provider;
import javax.telephony.ResourceUnavailableException;
import javax.telephony.Terminal;

import org.devrealm.jtapitutorial.bootstrap.ProviderService;

public class JTapiDiscovery {
public static void main (String[] args) {
Provider provider = ProviderService.getProvider();
//Print all the available addresses of the system.
try {
Address[] addresses = provider.getAddresses();
System.out.println("Avaialable Addresses : ");
for (int i = 0; i < addresses.length; i++) {
System.out.println("Address : " + addresses[i].getName());
}
} catch (ResourceUnavailableException e) {
e.printStackTrace();
}
//Print all the available terminals of the system.
try {
Terminal[] terminals = provider.getTerminals();
System.out.println("Avaialable Terminals : ");
for (int i = 0; i < terminals.length; i++) {
System.out.println("Terminal : " + terminals[i].getName());
}
} catch (ResourceUnavailableException e) {
e.printStackTrace();
}
//Always remember to shutdown the provider,
//otherwise the application won't return.
provider.shutdown();
}
}

So the JTapiDiscovery class, utilizing the previous ProviderService class, first retrieves the Provider object and start working with this.

If you take a look at the Javadoc of the Jtapi, the Provider interface supply a bunch of useful methods to retrieve the Addresses, Terminals, Capabilities etc, from the Provider’s domain. Thus, an array of Addresses is being retrieved and printed out. Similarly, an array of Terminals is being retrieved and printed out.

Notice, that its not the actual object that is printed out, but the name of the Address or the Terminal in question each time. As we will see in a future articles, an Address or Terminal interface among other methods, provides a getName() method in order to retrieve the unique name of the object. The getName() method is the main way to interact with the end users, since an Address object is known to the user only by its name, for example the extension number of his telephone set.

Also notice that the Provider’s methods _provider.getAddresses()_ and _provider.getTerminals()_ throw an exception of type ResourceUnavailableException that must handled when for example someone request an Address or Terminal that doesn’t exist or is not provided by this Jtapi service.

Finally, there is a call to the Provider’s method _provider.shutdown()_. This method, request the Provider to move the the state Provider.SHUTDOWN and the application to return. Provider’s states and state-transitions is the next issue to discuss.

Provider states

The Provider object can be in any of the following three states:

• Provider.IN_SERVICE: This state indicates that the Provider is currently alive and available for use.

• Provider.OUT_OF_SERVICE: This state indicates that a Provider is temporarily not available for use. Many methods in the Java Telephony API are invalid when the Provider is in this state. Providers may come back in service at any time, however, the application can take no direct action to cause this change.

• Provider.SHUTDOWN: This state indicates that a Provider is permanently no longer available for use. Most methods in the Java Telephony API are invalid when the Provider is in this state. Applications may use the Provider.shutdown() method on this interface to cause a Provider to move into the Provider.SHUTDOWN state.

When first the Provider is instantiated using the _JtapiPeer.getProvider(providerString)_ method, the Provider object returned is in the state IN_SERVICE and can be used straight away.

When an application calls _provider.shutdown()_, Provider is moving to the SHUTDOWN state, JTAPI loses communications permanently with the telephony subsystem and the application can assume that the Provider will not come up again, so the application must handle a complete shutdown. Applications invoke the Provider.shutdown() method when they no longer intend to use the Provider, usually, right before they exit. This method is intended to allow the Provider to perform any necessary cleanup that would not be handled when the Java objects are garbage collected. The
Provider.shutdown() method causes the Provider to move into the Provider.SHUTDOWN state where it will stay indefinitely. If the Provider is already in the Provider.SHUTDOWN state, this method does nothing.

Useful also for a developer, might be the Provider’s method, _provider.getState()_. This method will return a constant integer value that denotes the state of the provider as follows:

• Provider.IN_SERVICE: Constant Value 16

• Provider.OUT_OF_SERVICE: Constant Value 17

• Provider.SHUTDOWN: Constant Value 18

The figure below shows the allowable state transitions for the Provider object.

Provider states transition

Conclusion

Any kind of Java Telephony application you plan to implement will use the Provider object as the initial object to start interacting with the telephony subsystem. The Provider interface supplies additional methods that haven’t discussed over here but future articles that will describe the rest of the futures of JTapi, will present the full potential of Provider interface.

This article is an introduction to the Java Telephony API, presenting the most important elements of this and attempts to clarify some basic issues that will be the base for the following articles.

JTapi can be used to integrate CRM or other applications with a telephone system, create applications that handle incoming calls, create application that place outgoing call on behalf of a user, or in general provide an automated way for a user to handle his telephone set.

The purpose of JTAPI is to serve as an interface between a Java application and a telephone system. The point where this interface is located determines the degree of control an application has. In a first-party call control scenario the interface is located at a terminal. The application has the same degree of control a normal telephone user has. In a third-party call control scenario the interface is located inside the telephone system. Depending on the telephone system this internal access provides the application usually with more control capabilities than a first-party call control scenario.

First-party call control

Third-party call control

Figure 1: First-party and third-party call control in a Private Telephone Network with a PBX

A design goal of JTAPI has been to cover both scenarios. As a consequence JTAPI provides a model of the telephone system and of telephone calls that corresponds to the more general third-party view, even when JTAPI is used for first-party call control. A third-party view of a call does not distinguish between the local end and the remote end of a call. Instead, the two ends are symmetrical.

In this article, the discussion is about the third-party call capabilities of the JTAPI and more important how to control or monitor the elements that the JTAPI offers. Next is an introduction of what are the basic JTAPI elements.

Basic JTapi elements

Telephony applications, involve in the control or monitor of objects a telephone system exposes. Such objects could be logical objects, for example an Address, a Call, a Connection etc, or physical objects as a Terminal. Following is a list with the most important JTAPI objects that will be covered throughout this article series. This is an attempt to give an introduction so for everyone to be on the same page.

JTapiPeer

The JtapiPeer interface represents a vendor’s particular implementation of the Java Telephony API.

JtapiPeer is the first object an application must instantiate. Depending on the vendor’s implementation of this interface, one or more different services can be obtained by the JtapiPeer object.

Provider

A Provider represents the telephony software-entity that interfaces with a telephony subsystem.

A Provider is created and returned by the JtapiPeer.getProvider() method which is given a string to describe the desired Provider. This method sets up any needed communication paths between the application and the Provider. The string given is one of the services listed in the JtapiPeer.getServices().

The rest of the JTAPI objects are derived from the provider and also the provider is responsible for the various actions the application is designed to make with the JTapi. For example, provider is will deliver Address events in case we monitor an Address or create a call between a local Address and a remote Address (example of an outgoing call).

Important to notice is the term Provider’s domain which refers to the collection of Address and Terminal objects which are local to the Provider, and typically, can be controlled by the Provider. For example,the domain of a Provider for a PBX may be the Addresses and Terminals in that PBX. The Provider implementation controls access to Addresses and Terminals by limiting the domain it presents to the application.

Address

An Address object represents what we commonly think of as a “telephone number”.

The purpose of the address could be something different than a telephone number if the underlying network is not a telephone network. As an example if the underlying network is an IP network; then the address might represent an IP address (e.g. 192.168.0.100).

When the Address object is created, a unique string name is assigned to it (e.g. 15121) and does not change throughout the lifetime of the object. The method Address.getName() returns the name of the Address object.

Address objects may be classified into two categories: local and remote. Local Address objects are those addresses which are part of the local telephone system domain, for example the extension numbers of a PBX. These Address objects are created by the implementation of the Provider object when it is first instantiated. All of the Provider’s local addresses are reported via the Provider.getAddresses() method. Remote Address objects are those outside of the Provider’s domain which the Provider learns about during its lifetime through various happenings (e.g. an incoming call from a currently unknown address). Remote Addresses are not reported via the Provider.getAddresses() method.

Note that applications never explicitly create new Address objects.

Terminal

A Terminal represents a physical hardware endpoint connected to the telephony domain. In other words, a Terminal is the telephone set of a PBX.

When the Terminal object is created, a unique string name is assigned to it and does not change throughout the lifetime of the object. The method Terminal.getName() returns the name of the Terminal. Important to notice here is that in contrary with the Address name, the name of the Terminal may not have any real-world interpretation since in order to interact with a Terminal (e.g. call a Terminal) we use the Address assigned to this Terminal.

Terminal objects may be classified into two categories: local and remote. Local Terminal objects are those terminals which are part of the local telephone system domain, for example the telephone sets of a PBX. These Terminal objects are created by the implementation of the Provider object when it is first instantiated. All of the Provider’s local terminals are reported via the Provider.getTerminals() method. Remote Terminal objects are those outside of the Provider’s domain which the Provider learns about during its lifetime through various happenings (e.g. an incoming call from a currently unknown address). Remote Terminal objects are not reported via the Provider.getTerminals() method.

Note that applications never explicitly create new Terminal objects.

Address and Terminal objects

Address and Terminal objects exist in a many-to-many relationship. An Address object may have zero or more Terminals associated with it. For each Terminal associated with an Address, that Terminal must also reflect its association with the Address. Since the implementation creates Address (and Terminal) objects, it is responsible for insuring the correctness of these relationships. The Terminals associated with an Address is given by the Address.getTerminals() method and the Addresses associated with a Terminal is given by the Terminal.getAddresses().

An association between an Address and Terminal object indicates that the Terminal contains the Address object as one of its telephone number addresses. In many instances, a telephone set (represented by a Terminal object) has only one telephone number (represented by an Address object) associated with it. In more complex configurations, telephone sets may have several telephone numbers associated with them. Likewise, a telephone number may appear on more than one telephone set.

Call

A Call object models a telephone call.

A Call can have zero or more Connections. A two-party call has two Connections, and a conference call has three or more Connections. Each Connection models the relationship between a Call and an Address, where an Address identifies a particular party or set of parties on a Call.

A Call maintain a list of the Connections on that Call. Applications obtain an array of Connections associated with the Call via the Call.getConnections() method. A Call retains a reference to a Connection only if it is not in the Connection.DISCONNECTED state. Therefore, if a Call has a reference to a Connection, then that Connection must not be in the Connection.DISCONNECTED state. When a Connection moves into the Connection.DISCONNECTED state (e.g. when a party hangs up), the Call loses its reference to that Connection which is no longer reported via the Call.getConnections() method.

The Provider maintains knowledge of the calls currently associated with it. Applications may obtain an array of these Calls via the Provider.getCalls() method. A Provider may have Calls associated with it which were created before it came into existence. It is the responsibility of the implementation of the Provider to model and report all existing telephone calls which were created prior to the Provider’s lifetime. The Provider maintains references to all calls until they move into the Call.INVALID state.

Applications may create new Calls using the Provider.createCall() method. A new Call is returned in the Call.IDLE state. Applications may then use this idle Call to place new telephone calls. Once created, this new Call object is returned via the Provider.getCalls() method.

Address and Call objects

Address objects represent the logical endpoints of a telephone call. A logical view of a telephone call views the call as originating from one Address endpoint and terminates at another Address endpoint.

Address objects are related to Call objects via the Connection object. The Connection object has a state which describes the current relationship between the Call and the Address. Each Address object may be part of more than one telephone call, and in each case, is represented by a separate Connection object. The Address.getConnections() method returns all Connection objects currently associated with the Call.

An Address is associated with a Call until the Connection moves into the Connection.DISCONNECTED state. At that time, the Connection is no longer reported via the Address.getConnections() method. Therefore, the Address.getConnections() method will never report a Connection in the Connection.DISCONNECTED state.

The Java Telephony API specification states that the implementation is responsible for reporting all existing telephone calls when a Provider is first created. This implies that an Address object must report information regarding existing telephone calls to that Address. In other words, Address objects must reports all Connection objects which represent existing telephone calls.

Terminal and Call objects

Terminal objects represent the physical endpoints of a telephone call. With respect to a single Address endpoint on a Call, multiple physical Terminal endpoints may exist. Terminal objects are related to Call objects via the TerminalConnection object. TerminalConnection objects are associated with Call indirectly via Connections. A Terminal may be associated with a Call only if one of its Addresses is associated with the Call. The TerminalConnection object has a state which describes the current relationship between the Connection and the Terminal. Each Terminal object may be part of more than one telephone call, and in each case, is represented by a separate TerminalConnection objet. The Terminal.getTerminalConnections() method returns all TerminalConnection object currently associated with the Terminal.

A Terminal object is associated with a Connection until the TerminalConnection moves into the TerminalConnection.DROPPED state. At that time, the TerminalConnection is no longer reported via the Terminal.getTerminalConnections() method. Therefore, the Terminal.getTerminalConnections() method never reports a TerminalConnection in the TerminalConnection.DROPPED state.

The Java Telephony API specification states that the implementation is responsible for reporting all existing telephone calls when a Provider is first created. This implies that an Terminal object must report information regarding existing telephone calls to that Terminal. In other words, Terminal objects must report all TerminalConnection objects which represent existing telephone calls.

Connection

A Connection represents a link (i.e. an association) between a Call object and an Address object.

The purpose of a Connection object is to describe the relationship between a Call object and an Address object. A Connection object exists if the Address is a part of the telephone call. Applications use the Connection.getCall() and Connection.getAddress() methods to obtain the Call and Address associated with this Connection, respectively.

From one perspective, an application may view a Call only in terms of the Address/Connection objects which are part of the Call. This is termed a logical view of the Call because it ignores the details provided by the Terminal and TerminalConnection objects which are also associated with a Call. In many instances, simple applications (such as an outcall program) may only need to concern itself with the logical view. In this logical view, a telephone call is views as two or more endpoint addresses in communication. The Connection object describes the state of each of these endpoint addresses with respect to the Call.

Connection objects are immutable in terms of their Call and Address references. In other words, the Call and Address object references do not change throughout the lifetime of the Connection object instance. The same Connection object may not be used in another telephone call. The existence of a Connection implies that its Address is associated with its Call in the manner described by the Connection’s state.

Although a Connection’s Address and Call references remain valid throughout the lifetime of the Connection object, the same is not true for the Call and Address object’s references to this Connection. Particularly, when a Connection moves into the Connection.DISCONNECTED state, it is no longer listed by the Call.getConnections() and Address.getConnections() methods. Typically, when a Connection moves into the Connection.DISCONNECTED state, the application loses its references to it to facilitate its garbage collection.

Connections objects are containers for zero or more TerminalConnection objects. Connection objects represent the relationship between the Call and the Address, whereas TerminalConnection objects represent the relationship between the Connection and the Terminal. The relationship between the Call and the Address may be viewed as a logical view of the Call.

The relationship between a Connection and a Terminal represents the physical view of the Call, i.e. at which Terminal the telephone calls terminates.

Resources:

• Sun Java Telephony API (JTAPI)

• JTapi Tutorial by Marcel Graf/Zurich/IBM@IBMCH